FROM --platform 是什么
在 Dockerfile 里给 FROM 指定 --platform，可以显式声明该阶段使用的镜像架构。配合 BuildKit 预定义变量，就能写出「编译阶段跑构建机架构、产出目标架构」的标准多架构构建模式：编译类任务在原生架构上高速执行，最终运行阶段用目标架构镜像，产物无需模拟运行。这些变量由 BuildKit 按目标平台注入，老版本构建器不提供。
基本信息
| 预定义变量 | BUILDPLATFORM、BUILDOS、BUILDARCH、TARGETPLATFORM、TARGETOS、TARGETARCH、TARGETVARIANT |
|---|---|
| 语法 | FROM --platform=$BUILDPLATFORM golang:1.23 AS build |
| 声明要求 | 变量必须在 FROM 之后用不带赋值的 ARG 重新声明才可用 |
| 依赖 | BuildKit：docker buildx 或 Docker 23+ 默认构建 |
| 配套参数 | 构建命令用 --platform linux/amd64,linux/arm64 指定目标 |
| 固定写法 | FROM --platform=linux/amd64 也可写死，代价是失去可移植性 |
典型使用场景
- Go、Rust 等交叉编译友好的语言：一次构建出多架构二进制
- 前端构建阶段放在构建机架构上，只让运行阶段使用目标架构
- 需要在多架构构建里按 TARGETARCH 选择不同的依赖包
- 排查 exec format error：确认运行阶段用的镜像架构与目标节点一致
- 固定某个阶段的平台做可复现构建，避免构建机架构漂移影响产物
交叉编译标准写法
交叉编译标准写法
# 第一行声明前端版本，保证 ARG 与 --platform 行为一致
# syntax=docker/dockerfile:1
# 编译阶段固定跑构建机架构，速度最快
FROM --platform=$BUILDPLATFORM golang:1.23 AS build
ARG TARGETOS TARGETARCH
WORKDIR /src
COPY . .
RUN GOOS=$TARGETOS GOARCH=$TARGETARCH go build -o /out/app .
# 运行阶段使用目标平台镜像
FROM alpine:3.20
COPY --from=build /out/app /usr/local/bin/app
ENTRYPOINT ["/app"]变量含义对照
| 变量 | 取值示例 | 用在哪 |
|---|---|---|
| BUILDPLATFORM | linux/amd64 | 编译阶段镜像，取构建机架构 |
| TARGETPLATFORM | linux/arm64 | 运行阶段镜像，取目标架构 |
| TARGETOS | linux | 设置 GOOS 等编译目标系统 |
| TARGETARCH | arm64 | 设置 GOARCH 等编译目标架构 |
| TARGETVARIANT | v7 | 32 位 ARM 的变体标识 |
TARGETARCH 取值为 arm64 这类 Docker 架构名，与部分工具链使用的 aarch64 命名不同，需要转换时在构建脚本里做映射而不是直接拼接。
运行阶段若也要按目标平台切换基础镜像，可写 FROM --platform=$TARGETPLATFORM alpine:3.20；不显式指定时该阶段默认取目标平台，因此多数场景只给编译阶段加 --platform 即可。