Docker Manifest List 实现多架构镜像自动匹配，核心是按本地 CPU 架构（如 linux/amd64/arm64）拉取对应版本；需启用 CLI 实验性功能、验证仓库支持 OCI v1.0+、用 buildx 或 manifest 工具构建/聚合清单，并通过 imagetools inspect 验证平台条目。
一套代码适配多种芯片，关键不是改代码，而是让镜像能“自己选对版本”。Docker 的 Manifest List 就是这个自动匹配机制的底层支撑——它不存实际内容，只是一份带平台标记的“索引”，拉取时由 Docker 客户端按本地 CPU 架构（如 linux/amd64 或 linux/arm64）自动挑对应镜像。
确认基础环境是否就绪
不是所有环节默认支持多架构，这几项必须提前验证：
- 本地 Docker CLI 启用实验性功能：在 ~/.docker/config.json 中添加 "experimental": "enabled"
- 镜像仓库支持 OCI v1.0+ Manifest List：Docker Hub、GHCR、ECR、Harbor ≥ 2.0 均可；私有 Harbor 需开启 content_trust 并设为 OCI 模式
- 运行 docker buildx imagetools inspect nginx:latest 测试能否解析远程清单，失败说明连通性或权限有问题
用 buildx 一键构建并推送（推荐方式）
这是最稳定、适合 CI/CD 的路径，全程自动完成构建、上传、清单生成，无需手动打多个 tag 或合并。
- 启用 QEMU 模拟支持：docker run --privileged multiarch/qemu-user-static --reset -p yes
- 创建并激活多架构构建器：docker buildx create --use --name mybuilder && docker buildx inspect --bootstrap
- 执行构建命令（例如同时支持 x86_64 和 ARM64）：
docker buildx build \
--platform linux/amd64,linux/arm64 \
--push \
-t your-registry.com/app:v1.2 .
执行完后，app:v1.2 在仓库中就是一个 Manifest List，含两个平台各自的镜像摘要。
已有单架构镜像？用 manifest 手动聚合
适用于已分别构建好 app:v1.2-amd64 和 app:v1.2-arm64 的场景：
- 确保各镜像已推送到仓库，并带明确 tag
- 创建清单：
docker manifest create your-registry.com/app:v1.2 \
your-registry.com/app:v1.2-amd64 \
your-registry.com/app:v1.2-arm64 - 补全平台元数据（避免部分客户端识别异常）：
docker manifest annotate your-registry.com/app:v1.2 \
your-registry.com/app:v1.2-amd64 --arch amd64 --os linux - 最后推送：docker manifest push your-registry.com/app:v1.2
验证是否真正生效
不用跑容器，光看元数据就能确认：
- docker buildx imagetools inspect your-registry.com/app:v1.2 —— 输出中应明确列出 linux/amd64 和 linux/arm64 等 platform 条目
- 在不同机器上执行 docker pull your-registry.com/app:v1.2：
Intel 服务器会拉取 amd64 层，M2 Mac 或树莓派会拉取 arm64 层 - 强制测试某架构（比如 x86 机器跑 ARM）：
docker run --platform linux/arm64 -it your-registry.com/app:v1.2
