必须启用Docker实验性功能才能使用buildx：Docker Desktop需勾选设置，Linux需配置daemon.json并重启；否则buildx命令报错。执行docker buildx version验证，install注册为默认后端，create前先rm旧实例，inspect --bootstrap启动QEMU模拟器以支持多平台构建。
docker buildx create --use 之前必须确认实验性功能已启用
Buildx 不是开箱即用的子命令，Docker Desktop 用户需在设置中勾选 Enable experimental features；Linux CLI 用户则要确保 /etc/docker/daemon.json 包含 "experimental": true 并重启 Docker daemon。否则 docker buildx version 可能报错或返回空，后续所有命令都会失败。
常见错误现象：docker buildx create: command not found（旧版 Docker）、no builder instance found（未启用实验性）或 error: could not create a builder instance（权限/配置缺失）。
- 运行
docker buildx version验证是否识别到 buildx - 执行
docker buildx install将 buildx 注册为docker build的默认后端（非必需但强烈推荐） - 创建 builder 前先删掉旧实例：
docker buildx rm mybuilder，避免平台冲突
docker buildx inspect --bootstrap 是启动 QEMU 模拟器的关键步骤
只运行 docker buildx create --use --platform linux/amd64,linux/arm64 不够——它只是声明支持哪些平台，但底层没有实际运行时环境。缺了 docker buildx inspect --bootstrap，buildx 会卡在 “no valid drivers found”，因为 container-based builder 没被拉起，QEMU 模拟器也没加载。
这步会自动拉取 moby/buildkit:latest 容器镜像，并挂载 /dev/kvm（如可用）或启用纯用户态 QEMU 模拟。ARM64 构建依赖它来运行交叉编译工具链和基础镜像中的二进制程序。
- 首次运行可能耗时较长（需下载 ~50MB BuildKit 镜像）
- 若宿主机是 ARM64（比如 M1/M2 Mac），
linux/arm64可原生执行，但linux/amd64仍需 QEMU 模拟 - 检查是否生效：运行
docker buildx inspect，输出中Platforms:行应明确列出目标架构，例如linux/amd64, linux/arm64
Dockerfile 中硬编码 x86_64 工具或二进制会导致 arm64 构建失败
Python 项目最容易踩的坑是依赖预编译轮子（wheel）。比如 pip install psycopg2-binary 默认只提供 manylinux_x86_64 轮子，在 --platform linux/arm64 下会跳过安装、回退到源码编译，而源码编译又依赖 pg_config 和 libpq-dev —— 这些在 ARM64 基础镜像里往往没装或版本不匹配。
同样危险的是在 RUN 指令中直接下载 x86_64 二进制，例如：RUN curl -L https://example.com/tool-x86_64 -o /usr/local/bin/tool。该命令在 arm64 构建阶段会静默下载一个无法执行的文件。
- 改用源码版包：
psycopg2（不含-binary）或numpy改为numpy==1.26.4（该版本提供 arm64 wheel） - 用
FROM --platform=linux/amd64 python:3.9-slim显式指定基础镜像平台（仅当确实需要跨平台构建工具时） - 在
pyproject.toml中加平台约束：requires-python = ">=3.9"+[project.optional-dependencies]分离架构敏感依赖
多阶段构建不干净会让镜像体积暴涨且混入编译工具
BuildKit 默认启用 layer 缓存，但多平台构建下容易把 build 阶段的 gcc、python3-dev、build-essential 等全打进 final 镜像。一个本该 100MB 的 Python 服务镜像，可能变成 300MB+，还带一堆不该存在的头文件和静态库。
根本原因：final 阶段的 COPY --from=builder 写错位置，或误在 final 阶段又执行了 apt-get install；更隐蔽的是 COPY . /app 放在 final 阶段之后，导致整个构建上下文（含 .git、__pycache__、虚拟环境）被塞进去。
- 务必使用显式多阶段命名：
FROM python:3.9-slim AS builder→FROM python:3.9-slim AS runtime - final 阶段只
COPY --from=builder /app/dist/*.whl /tmp/或COPY --from=builder /usr/local/lib/python3.9/site-packages/ /usr/local/lib/python3.9/site-packages/ - 构建时加
--no-cache或BUILDKIT_PROGRESS=plain观察每层内容，确认 final 镜像没残留/usr/bin/gcc或/usr/include/python3.9
构建多平台 Python 镜像最难的不是命令敲对，而是让每一层都“知道自己在哪个 CPU 上跑”。从基础镜像、工具链、依赖轮子到最终 COPY 路径，任何一处平台假设错位，都会在 docker run 时才暴露为 exec format error 或静默崩溃。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
