必须显式指定全部目标架构，如linux/amd64,linux/arm64；不写--platform则仅构建宿主机架构，无法生成manifest list；--push不可省略，需用docker buildx imagetools inspect验证远程清单。
docker buildx build --platform 必须显式指定全部目标架构
不写 --platform 或只写部分架构（比如漏掉 linux/arm64），Buildx 默认只构建当前宿主机架构，不会自动生成 manifest list。哪怕你本地是 ARM64 机器，也绝不会自动包含 amd64 变体——这会导致其他平台用户拉取失败或 fallback 到错误镜像。
实操建议：
- 始终用完整、明确的平台列表，例如：
linux/amd64,linux/arm64,linux/arm/v7 - 避免使用模糊别名（如
arm），Docker 不识别；必须用 OCI 标准格式 - CI/CD 中建议从环境变量注入平台列表，但需做非空校验，防止空值导致单架构构建
--push 参数不可省略，且不能靠 docker push 补救
docker buildx build --push 是原子操作：它在所有子架构镜像构建成功后，才提交 manifest list 到 registry。如果拆成 build + 手动 docker push，你会得到多个独立镜像，但没有 manifest list——registry 里只有散列镜像，docker pull your-app:latest 将无法自动选架构，甚至可能拉到 x86_64 镜像后在 ARM 设备上报 exec format error。
常见错误现象：
- 本地
docker buildx build成功，但远程docker manifest inspect报错 “no such manifest” - 镜像仓库页面显示多个 tag（如
:latest-amd64,:latest-arm64），说明没走 manifest 流程
必须验证远程 manifest list 而非本地镜像
本地 docker images 看到的只是缓存镜像，不代表远程 registry 已正确聚合。真正决定运行时行为的是 registry 上的 manifest list。
验证命令必须用：
-
docker buildx imagetools inspect your-registry/your-app:latest—— 显示各架构 digest 和平台信息 - 不要用
docker manifest inspect（已弃用且不支持 Buildx 生成的清单） - 检查输出中
manifests字段是否包含全部预期架构，且每个platform.architecture值准确（如arm64而非arm）
QEMU 模拟不是万能的，关键路径必须真机验证
Buildx 依赖 QEMU 模拟非本机架构（如 x86_64 机器上构建 arm64），这对编译阶段基本可靠，但无法捕获运行时差异：glibc 版本偏移、内核模块缺失、硬件加速指令（如 ARM SVE）调用失败等。
安全一致性真正落地的环节在测试：
- 对每个目标架构，至少用一台真实设备（如树莓派、M2 Mac、AWS Graviton 实例）执行
docker run --rm your-app:latest /bin/sh -c 'echo ok' - 若应用含 CGO 或系统调用（如
seccomp规则、capabilities），必须在对应架构上跑集成测试 - CI 中可并行触发多架构测试 job，但不能跳过真机环节——模拟器过不了的坑，上线就炸
最易被忽略的一点：manifest list 本身无签名，--push 后若 registry 支持，务必启用 content trust（DOCKER_CONTENT_TRUST=1）并配合 Notary 签署整个清单，否则攻击者可篡改 manifest 指向恶意子镜像。
