需初始化 buildx builder 实例并启用实验性功能；运行 docker buildx create --use 创建多架构 builder，再执行 docker buildx inspect --bootstrap 启动 container-based 构建器，否则报 “no valid drivers found”。
buildx build 报错 “no valid drivers found”
没启用 buildx 的 builder 实例，或者 Docker Desktop 未开启实验性功能。buildx 不是默认激活的子命令，得手动初始化。
- 运行
docker buildx version确认 buildx 已安装（Docker 20.10+ 自带，旧版需手动装） - 执行
docker buildx install把 buildx 注册为默认docker build后端（可选但推荐） - 创建并切换到多架构 builder：
docker buildx create --use --name mybuilder --platform linux/amd64,linux/arm64 - 启动它：
docker buildx inspect --bootstrap—— 这步会拉起 container-based builder，缺这步就报 “no valid drivers”
构建时指定 --platform 却没生效
只加 --platform 不够，底层 builder 必须支持对应平台，且镜像基础层、构建过程中的所有工具链都得兼容目标 CPU 架构。
- 确认 builder 支持目标平台：
docker buildx inspect输出里看Platforms:行，必须含linux/arm64这类条目 - Dockerfile 中避免硬编码 x86_64 工具：比如用
apt-get install python3没问题，但用curl https://.../binary-x86_64就会在 arm64 上失败 - Python 项目尤其注意：如果用了预编译的 C 扩展（如
numpy、psycopg2-binary），它们通常只提供 amd64 轮子，arm64 构建时会 pip install 失败或降级编译 —— 建议改用psycopg2（源码版）或在pyproject.toml中约束platform_machine == "x86_64"并分平台构建
Python 镜像体积暴涨 200MB+，和本地 pip install 结果不一致
buildx 的多平台构建默认启用 BuildKit，而 BuildKit 的缓存机制和 layer 提交逻辑跟传统 build 不同，加上交叉编译环境残留，容易把构建依赖（如 gcc、python3-dev）意外打进最终镜像。
- 务必用多阶段构建：build 阶段装编译工具 + 构建依赖，final 阶段只 COPY 编译产物 + 运行时依赖
- 检查
Dockerfile是否误写COPY . /app在 final 阶段之后 —— 这会让整个 build context（含__pycache__、.git、虚拟环境）进镜像 - 禁用 BuildKit 的缓存污染：临时加
--no-cache测试，或用BUILDKIT_PROGRESS=plain docker buildx build ...查看每层实际内容
推送到 registry 后，docker pull 显示 “manifest unknown”
镜像推上去了，但 registry 返回 404，常见于用了 --push 却没配好 --platform 或 tag 冲突，导致部分平台镜像缺失，registry 拒绝生成 manifest list。
立即学习“Python免费学习笔记（深入）”；
- 必须显式指定完整平台列表：
--platform linux/amd64,linux/arm64，不能只写一个 - tag 必须唯一且不含 latest（某些 registry 对 latest + 多平台支持差）：用语义化版本如
v1.2.3，并确保所有平台镜像共用同一 tag - 推送后验证：
docker buildx imagetools inspect your-registry/app:v1.2.3—— 正常输出应列出多个Manifests条目，每个带Platform字段
多平台构建真正的麻烦不在命令本身，而在 Python 生态对交叉编译的隐式假设：pip 默认只找当前架构轮子、setuptools 编译时读取宿主机 uname -m、甚至某些 CFFI 绑定会硬编码指令集。别信“buildx 一键多平台”，得一层层验构建产物的架构和符号表。
