Docker 在 macOS 上默认使用 linux/amd64 平台

问题描述

如果您在 Apple Silicon（M1/M2）芯片的 macOS 上使用 Docker，可能会遇到一个常见问题：默认情况下，Docker 会自动选择与您的硬件架构（arm64）匹配的平台，而非通常部署环境常用的 linux/amd64 平台。

这会导致在本地构建的 Docker 镜像无法在基于 AMD64 架构的生产环境（如 AWS EC2、ECS 或其他 Linux 服务器）中正常运行。

解决方案

有多种方法可以强制 Docker 默认使用 linux/amd64 平台，以下是几种最有效的方法：

方法一：设置环境变量（推荐）

通过设置 DOCKER_DEFAULT_PLATFORM 环境变量，可以全局配置 Docker 默认使用的平台：

# 临时设置（仅当前终端会话有效）
export DOCKER_DEFAULT_PLATFORM=linux/amd64

# 永久设置（添加到 shell 配置文件）
echo 'export DOCKER_DEFAULT_PLATFORM=linux/amd64' >> ~/.zshrc  # 对于 zsh
echo 'export DOCKER_DEFAULT_PLATFORM=linux/amd64' >> ~/.bashrc # 对于 bash

TIP

设置后需要重新加载 shell 配置或打开新的终端窗口：

source ~/.zshrc  # 或 source ~/.bashrc

方法二：Dockerfile 中指定平台

在 Dockerfile 的 FROM 指令中直接指定平台（对于多阶段构建，只需在第一阶段指定）：

FROM --platform=linux/amd64 python:3.7-alpine
# 后续指令...

方法三：docker-compose 配置

在 docker-compose.yml 文件中为每个服务指定平台：

services:
  frontend:
    platform: linux/amd64
    build: frontend
    ports:
      - 80:80
  
  backend:
    platform: linux/amd64
    build: backend

方法四：单次命令设置

对于单次构建或运行命令，可以在命令前设置环境变量：

DOCKER_DEFAULT_PLATFORM=linux/amd64 docker build .
DOCKER_DEFAULT_PLATFORM=linux/amd64 docker-compose build

方法五：使用自定义 shell 函数

创建 shell 函数自动为 docker run 和 docker build 命令添加平台参数：

# 添加到 ~/.zshrc 或 ~/.bashrc
docker() {
  if [[ $(uname -m) == "arm64" ]] && [[ "$1" == "run" || "$1" == "build" ]]; then
    /usr/local/bin/docker "$1" --platform linux/amd64 "${@:2}"
  else
    /usr/local/bin/docker "$@"
  fi
}

注意事项

1. 如果已经下载了错误平台的镜像，需要先删除该镜像：

   docker image rm your_image_name

2. 某些情况下可能需要使用 buildx 进行跨平台构建：

   docker buildx build --platform linux/amd64 .

总结

对于 Apple Silicon macOS 用户，推荐设置 DOCKER_DEFAULT_PLATFORM 环境变量作为长期解决方案，这样可以确保所有 Docker 命令默认使用 linux/amd64 平台，避免与生产环境架构不兼容的问题。

对于特定项目，也可以在 Dockerfile 或 docker-compose.yml 中直接指定平台，这样能确保项目级别的跨团队一致性。