Docker的FROM指令通过--platform参数指定目标平台实现多架构构建，需配合buildx和多阶段构建使用；标准写法为FROM --platform=linux/arm64 golang:1.21 AS builder，且必须置于镜像名前。
Docker 的 FROM 指令本身不直接“支持多架构”，但它可以通过 --platform 参数显式指定目标平台，这是实现多架构构建的关键起点。
真正起作用的不是镜像本身有多架构能力，而是你在构建时告诉 Docker：这个阶段要用哪个架构的基础镜像。配合 buildx 和多阶段构建，就能让不同阶段适配不同平台（比如构建用 linux/amd64，运行用 linux/arm64），或统一为多个平台生成镜像。
FROM 指令中指定平台的写法
标准语法：
FROM --platform=linux/arm64 golang:1.21 AS builder
或
FROM --platform=linux/amd64 ubuntu:22.04
-
--platform必须写在FROM后、镜像名前； - 它只影响该
FROM阶段拉取和使用的基础镜像架构，不影响后续指令是否能跨平台运行（实际执行仍依赖 buildx + QEMU 或原生节点）； - 如果省略，Docker 默认使用当前宿主机架构（比如你在 x86 机器上不加
--platform，就只会拉linux/amd64镜像）。
多架构构建中 FROM 的典型用法
✅ 推荐：每个阶段都明确指定平台（尤其构建阶段）
# 构建阶段：固定用 amd64 编译（因某些工具链仅支持 x86） FROM --platform=linux/amd64 golang:1.21 AS builder WORKDIR /app COPY . . RUN CGO_ENABLED=0 GOOS=linux go build -o myapp . # 运行阶段：适配最终部署目标（可同时生成 arm64 和 amd64 版本） FROM --platform=linux/arm64 alpine:latest RUN apk add --no-cache ca-certificates WORKDIR /root COPY --from=builder /app/myapp . CMD ["./myapp"]
⚠️ 注意：上面这个写法本身只能构建出 linux/arm64 镜像。若想一次产出 amd64 + arm64 两个版本，必须配合 docker buildx build --platform linux/amd64,linux/arm64 命令，它会自动为每个平台重新解析整个 Dockerfile，并分别执行各 FROM --platform=xxx 指令。
实际构建时的关键配合点
-
必须启用 BuildKit（推荐全局开启）：
OpenClaw Docker Setup下载在 Linux 上通过 Docker 运行 OpenClaw，并使用 Tailscale 实现远程访问。⚠️ 涉及 sudo、Docker、Tailscale和凭证挂载——请先查阅安全章节...
export DOCKER_BUILDKIT=1
-
使用 buildx 创建多架构 builder：
docker buildx create --use --name multiarch --driver docker-container docker buildx inspect --bootstrap
-
启动 QEMU 模拟支持（x86 主机构建 ARM 镜像必需）：
docker run --privileged multiarch/qemu-user-static --reset -p yes
-
构建并推送多架构镜像：
docker buildx build \ --platform linux/amd64,linux/arm64 \ --tag your-registry/app:v1.0 \ --push \ .
此时，Docker 会：
- 对
linux/amd64：用--platform=linux/amd64的golang和alpine镜像； - 对
linux/arm64：用--platform=linux/arm64的对应镜像（前提是这些镜像本身是多架构的，比如官方golang、alpine都支持）。
常见误区提醒
- ❌ 不要以为
FROM golang:1.21自动适配所有架构 —— 它默认只拉当前机器架构的层； - ❌ 不要在
FROM里写--platform=$TARGETPLATFORM（那是 buildx 内部变量，Dockerfile 不识别）； - ✅ 官方镜像如
golang、alpine、ubuntu、nginx等大多已提供多架构 manifest，可放心搭配--platform使用； - ✅ 若自建基础镜像，需确保它本身已按多架构方式推送到仓库（即含 manifest list），否则
--platform会失败。
不复杂但容易忽略。核心就是：FROM --platform=xxx + buildx build --platform=xxx,yyy 两处配合到位，基础镜像自然就“多架构”了。
