背景

开发机上构建的二进制未必能在 Raspberry Pi 运行。多架构镜像需要同时正确处理构建平台、目标平台与原生依赖。

核心判断

  1. 构建阶段使用 BUILDPLATFORM，编译器显式接收 TARGETOS 与 TARGETARCH。
  2. 纯 Go 与 CGO 分别设计工具链，ARM 变体需要额外评估。
  3. 推送 manifest list 后分别在目标架构测试。

最小示例

下面保留核心逻辑；业务类型、调用入口和环境配置按项目补齐。

FROM --platform=$BUILDPLATFORM golang:1.24 AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
ARG TARGETOS TARGETARCH
RUN CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH \
    go build -o /out/app ./cmd/app

FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=build /out/app /app
ENTRYPOINT ["/app"]

边界与误区

示例固定版本只是可复现输入，不是最新工具链推荐。关闭 CGO 不适用于所有依赖；能交叉编译也不代表运行时 syscall 和性能都一样。

验证方式

分别检查 linux/amd64 与 linux/arm64 的镜像清单和运行结果。真实 ARM 节点上验证启动、TLS、持久化和基础性能，而不只依赖模拟器。

小结

用固定基础镜像和平台参数构建，分别验证 amd64、arm64 的运行时和依赖。