Windows上构建多架构镜像唯一可靠方式是启用Buildx+WSL2+Linux容器模式：需验证buildx支持linux/amd64、arm64等平台，正确指定--platform参数，使用多架构基础镜像，并通过--push一次性推送生成manifest list。
docker buildx build 是唯一可靠的方式，Windows 上用 Docker Desktop 构建多架构镜像，**必须启用 Buildx + WSL2 + Linux 容器模式**，其他路径（比如直接 docker build 或 Windows 容器模式）根本走不通。
确认 Buildx 已就绪且支持目标平台
Buildx 不是默认启用的“开箱即用”功能，即使 Docker Desktop 24.0+ 已集成，也要手动验证是否加载了目标平台。常见错误是执行 docker buildx build --platform linux/arm64 后，日志里出现 skipping build for linux/arm64: unsupported platform。
运行以下命令检查：
docker buildx inspect --bootstrap
输出中必须包含类似 Platforms: linux/amd64,linux/arm64,linux/arm/v7。若只有 linux/amd64，说明 QEMU 模拟器没加载成功，或构建器未正确初始化。此时应：
- 确保 Docker Desktop 设置中已勾选 Use the WSL 2 based engine 和 Enable integration with my default WSL distro
- 在 PowerShell 中运行
wsl -l -v，确认默认发行版为WslVersion: 2 - 右键托盘图标 → Switch to Linux containers（这步漏掉会导致全部失败）
- 执行
docker buildx create --use --name multiarch --driver docker-container --bootstrap强制重建构建器
docker buildx build --platform 的参数写法陷阱
--platform 不是模糊匹配，而是精确指定每个构建任务的目标架构。写错格式、漏写 OS 前缀、混用非法组合，都会导致部分平台被跳过或构建失败。
典型错误包括：
- 写成
--platform arm64→ 正确必须是linux/arm64 - 写成
--platform darwin/arm64→ BuildKit 不支持 macOS 目标镜像，会静默忽略 - 在 Windows 上只写
--platform linux/arm64→ 默认不构建本地平台，linux/amd64会被跳过，最终 manifest list 缺少 x86_64 版本 - 顺序不合理：把冷门平台放前面（如
linux/arm/v7,linux/amd64），会导致后续平台缓存命中率暴跌，构建变慢
推荐写法（兼顾兼容性与缓存效率）：
docker buildx build \ --platform linux/amd64,linux/arm64,linux/arm/v7 \ --tag ghcr.io/your/app:v1.0 \ --push \ .
Dockerfile 和基础镜像必须真正支持多架构
就算 Buildx 跑通了，Dockerfile 里一行错配的指令也能让整个多架构构建崩在 FROM 那步。核心原则：所有基础镜像必须提供对应平台的官方 tag，且不能含平台专属二进制。
安全选择：
-
FROM node:18-alpine✅ 多架构完整支持 -
FROM python:3.11-slim✅ 官方镜像自动分发各平台版本 -
FROM openjdk:17-jre-slim✅ 有arm64和amd64双版本
高危雷区：
-
FROM mcr.microsoft.com/windows/servercore:ltsc2022❌ Windows 专属，无法在 Linux 构建器上拉取 -
FROM some-unknown/image:latest❌ 若该镜像没推linux/arm64版本，构建直接报manifest unknown -
RUN apt-get install -y some-arm-only-package❌ 在linux/amd64构建时会失败
推送后为什么 docker pull 还报 exec format error
现象：命令返回 Successfully pushed，但树莓派上 docker pull your/app:v1.0 后 docker run 报 exec format error；或者 docker manifest inspect your/app:v1.0 显示只有一个平台。
本质不是构建失败，而是镜像仓库或客户端没按 OCI Index 解析 manifest list。关键排查点：
- 确认推送目标是支持 OCI v1.1 的仓库（Docker Hub、GHCR、Harbor ≥ 2.0），旧版私仓可能不识别 manifest list
- 在 ARM64 机器上执行
docker pull --platform linux/arm64 your/app:v1.0显式指定平台，排除客户端自动解析失败 - 用
docker manifest inspect your/app:v1.0查看输出中manifests数组长度是否 ≥ 2，且每个项的platform.architecture字段正确 - 避免使用
docker push单独推某个平台镜像——它只会覆盖单个 digest，破坏 manifest list
最常被忽略的一点：本地构建器必须用 --push 一次性完成构建+推送，拆成 build + push 两步，manifest list 就不会生成。
