Khắc phục lỗi 'no matching manifest for linux/arm64/v8' trên Apple Silicon (M1/M2/M3)

Tại sao lỗi này xảy raChuyển sang máy Mac dùng chip M1, M2 hoặc M3 thường là một sự nâng cấp đáng kể cho đến khi bạn cố gắng chạy một Docker stack cũ hơn. Bạn có thể thử pull một image quen thuộc—như MySQL 5.7 hoặc một bản build Python cũ—để rồi thấy quá trình bị treo và thất bại với lỗi sau:

no matching manifest for linux/arm64/v8 in the manifest list entries

Nguyên nhân gốc rễ là do sự không tương thích về kiến trúc. Apple Silicon sử dụng kiến trúc ARM64, trong khi các Docker image cũ thường được xây dựng riêng cho x86_64 (Intel/AMD). Khi bạn yêu cầu một image, Docker Desktop sẽ tìm kiếm trên registry phiên bản phù hợp với chip gốc của bạn. Nếu người duy trì (maintainer) chưa xuất bản bản build ARM64, Docker sẽ dừng lại.

Cách khắc phục nhanh: Ép nền tảng qua CLIBạn có thể bỏ qua lỗi này bằng cách yêu cầu Docker sử dụng phiên bản Intel của image một cách rõ ràng. macOS xử lý các tác vụ nặng thông qua Rosetta 2, giúp biên dịch các chỉ lệnh Intel cho chip ARM của bạn ngay lập tức. Nó không nhanh bằng mã nguồn gốc (native), nhưng vẫn giúp hoàn thành công việc.

Để pull một image không tương thích, hãy thêm flag --platform vào câu lệnh của bạn:

# Ví dụ: Pull MySQL 5.7, phiên bản thiếu hỗ trợ ARM gốc
docker pull --platform linux/amd64 mysql:5.7

Khi bạn đã sẵn sàng khởi chạy container, bạn phải chỉ định lại nền tảng để đảm bảo lớp giả lập vẫn hoạt động:

docker run -d --name my-db --platform linux/amd64 -e MYSQL_ROOT_PASSWORD=pass mysql:5.7

Cách khắc phục lâu dài: Cập nhật Docker ComposeViệc nhập các flag một cách thủ công rất tẻ nhạt, đặc biệt là trong môi trường làm việc nhóm nơi các đồng nghiệp có thể vẫn đang sử dụng máy Mac chạy chip Intel. Bạn có thể tự động hóa việc này bằng cách đưa yêu cầu nền tảng trực tiếp vào file docker-compose.yml.

Chỉ cần thêm thuộc tính platform: linux/amd64 vào service cụ thể:

services:
  db:
    image: mysql:5.7
    platform: linux/amd64
    environment:
      - MYSQL_ROOT_PASSWORD=root
    ports:
      - "3306:3306"

Cấu hình này đảm bảo rằng mọi thành viên trong nhóm đều pull cùng một phiên bản. Docker Compose sẽ tự động sử dụng image amd64 bất kể máy chủ là MacBook Pro M3 hay iMac chạy chip Intel cũ hơn.

Các lựa chọn thay thế tốt hơn về lâu dàiMặc dù việc giả lập qua Rosetta 2 rất tiện lợi, nhưng nó đi kèm với sự sụt giảm hiệu suất. Các container chạy giả lập thường giảm từ 20% đến 35% hiệu suất CPU và tiêu tốn pin nhiều hơn. Bất cứ khi nào có thể, hãy chuyển sang các image hỗ trợ ARM64 gốc.

• MySQL: Nâng cấp lên mysql:8.0 hoặc chuyển sang mariadb:latest, cả hai đều hỗ trợ ARM rất tốt.
• Postgres: Các phiên bản 13 và mới hơn đã được tối ưu hóa hoàn toàn cho ARM64.
• Development Runtimes: Sử dụng tag -slim hoặc -alpine cho Node.js và Python. Những bản này hầu như luôn hỗ trợ đa kiến trúc (multi-architecture). Trước khi quyết định sử dụng một image cũ, hãy kiểm tra phần "OS/ARCH" của nó trên Docker Hub. Nếu bạn không thấy arm64 trong danh sách, bạn sẽ cần đến giải pháp sử dụng flag platform.

Xác minh kết quảSau khi container của bạn đã hoạt động, bạn có thể kiểm tra lại xem nó có đang sử dụng đúng kiến trúc hay không. Chạy lệnh này để kiểm tra metadata:

docker inspect <container_id> | grep Architecture

Ngay cả trên máy Mac chạy chip ARM, kết quả trả về phải là "Architecture": "amd64". Bạn có thể thấy biểu tượng cảnh báo màu vàng trong bảng điều khiển Docker Desktop cho biết nền tảng image không khớp với máy chủ. Bạn có thể yên tâm bỏ qua điều này; đó chỉ là lời nhắc rằng container đang chạy dưới dạng giả lập.