解决 M1/M2 Mac Docker MySQL "no matching manifest for linux/arm64/v8" 错误

问题描述

在 Apple Silicon (M1/M2) 芯片的 Mac 上使用 Docker 时，尝试拉取 MySQL 镜像经常会遇到以下错误：

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

这个错误的原因是许多 Docker 镜像（特别是旧版本）尚未支持 Apple Silicon 使用的 ARM64 架构。Docker 在 M1/M2 机器上默认尝试拉取 ARM 兼容的镜像，但某些镜像（如特定版本的 MySQL）只提供 linux/amd64 架构的构建。

解决方案

方法一：在 docker-compose 中指定平台（推荐）

在 docker-compose.yml 文件中为 MySQL 服务添加 platform 字段：

version: '3'

services:
  db:
    image: mysql:5.7
    platform: linux/amd64  # 添加这一行
    volumes:
      - db_data:/var/lib/mysql
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: pass
      MYSQL_DATABASE: wp
      MYSQL_USER: wp
      MYSQL_PASSWORD: wp
    networks:
      - wpsite

方法二：使用原生 ARM64 镜像

Oracle 提供了原生支持 ARM64 的 MySQL 镜像：

version: "3.8"
services:
  mysql:
    image: mysql/mysql-server:8.0.23
    ports:
      - "3306:3306"
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: mydatabase
      MYSQL_ROOT_HOST: "%"

方法三：使用 MariaDB 替代

MariaDB 是 MySQL 的兼容替代品，原生支持 ARM64：

services:
  db:
    image: mariadb:10.5.8
    volumes:
      - db_data:/var/lib/mysql
    environment:
      MYSQL_ROOT_PASSWORD: pass
      MYSQL_DATABASE: wp
      MYSQL_USER: wp
      MYSQL_PASSWORD: wp

方法四：设置环境变量

在终端中设置默认平台环境变量：

# 对于 zsh shell
echo 'export DOCKER_DEFAULT_PLATFORM=linux/amd64' >> ~/.zshrc
source ~/.zshrc

# 对于 bash shell
echo 'export DOCKER_DEFAULT_PLATFORM=linux/amd64' >> ~/.bash_profile
source ~/.bash_profile

方法五：在 Docker 命令中指定平台

使用 docker run 命令时直接指定平台：

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

方法六：创建特定于平台的覆盖文件

对于团队开发，可以创建特定于平台的 docker-compose 覆盖文件：

1. 创建 docker-compose.mac.yml：

version: '2'
services:
  mysql:
    platform: linux/amd64

2. 启动时同时指定两个文件：

docker-compose -f docker-compose.yml -f docker-compose.mac.yml up

性能考虑

注意

虽然使用 --platform linux/amd64 可以让 x86 容器在 M1/M2 上运行，但这会通过 Rosetta 2 进行模拟，可能导致：

• 性能下降
• 内存使用增加
• 某些功能受限（如 Linux Native AIO）

原生 ARM64 MySQL 构建

如果需要在 M1/M2 上获得最佳性能，可以考虑：

1. 使用社区维护的 ARM64 MySQL 构建
2. 从源代码自行编译 MySQL
3. 等待官方提供完整的 ARM64 支持

总结

对于 Apple Silicon Mac 上的 MySQL Docker 问题，最简单的解决方案是在 docker-compose 中添加 platform: linux/amd64。对于新项目，考虑使用原生支持 ARM64 的 mysql/mysql-server 镜像或 MariaDB 替代方案。

提示

始终检查 Docker Hub 上镜像的最新支持情况，因为镜像的架构支持会随时间改进。