3. 容器化前置准备

把 Go 服务放进容器之前，真正决定镜像体积、启动速度和可移植性的，往往不是 Dockerfile 写得多花哨，而是二进制本身是怎么编译出来的。Go 的编译模型与 Java、Node.js 这类需要运行时解释或虚拟机的语言不同：Go 程序默认会被编译成一个包含运行时、垃圾回收器和调度器的独立可执行文件。理解这一点，是后续写出小体积、可复现镜像的前提。

静态编译与动态链接：镜像里到底需要什么

Go 的链接方式分为静态链接和动态链接两种。静态链接会把程序依赖的所有代码（包括 Go 运行时和部分系统库）都打包进最终的可执行文件，产物不依赖目标机器上的额外共享库；动态链接则把部分依赖留给运行时的 .so 文件，例如 glibc。是否静态，主要取决于两个因素：是否启用了 CGO，以及是否使用了 net、os/user 等会触发系统解析的包。

当 CGO_ENABLED=0 时，Go 使用纯 Go 实现的网络解析和用户查询，链接器默认产出静态可执行文件。此时可以把它放进一个几乎空的镜像里运行，例如 scratch 或 gcr.io/distroless/static，镜像里除了二进制和证书，几乎没有任何多余内容。反之，如果 CGO_ENABLED=1，程序会链接 glibc，就必须在运行镜像里提供兼容的 libc，否则启动时会报 no such file or directory 或 version 'GLIBC_2.xx' not found。

可以用一条命令快速判断产物类型：

# 查看是否动态链接
file app
# 输出示例：
# app: ELF 64-bit LSB executable, x86-64, dynamically linked, ...
# 或
# app: ELF 64-bit LSB executable, x86-64, statically linked, ...

# 查看依赖的动态库
ldd app
# 静态产物会输出 "not a dynamic executable"

CGO：能力与代价的权衡

CGO 让 Go 能调用 C 代码，常见于 SQLite、某些加密库、图像处理库以及依赖系统 DNS 的场景。它的代价是明显的：编译变慢、产物变大、可移植性下降、交叉编译变复杂。对于容器化服务，建议默认关闭 CGO，只有在确实需要某个 C 库时才开启，并明确记录原因。

如果必须开启 CGO，就要为运行镜像准备对应的 libc。常见做法是使用与构建阶段一致的发行版作为运行基础镜像，例如构建用 golang:1.22-bookworm，运行用 debian:bookworm-slim，避免 glibc 版本错配。另一种思路是改用 musl 静态链接（如 golang:alpine 配合 CGO_ENABLED=1 和 -ldflags '-linkmode external -extldflags "-static"'），但需要确认所用 C 库支持 musl。

交叉编译：一次构建，多架构运行

容器镜像经常需要同时支持 linux/amd64 和 linux/arm64。Go 的交叉编译非常直接，只需设置 GOOS 和 GOARCH：

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o app-amd64 .
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -o app-arm64 .

注意：交叉编译只有在 CGO_ENABLED=0 时才最顺畅。一旦开启 CGO，就需要为目标架构准备对应的 C 交叉编译工具链，复杂度显著上升。因此在 CI 中，推荐用 CGO_ENABLED=0 配合 GOARCH 矩阵来产出多架构二进制，再分别构建镜像并合并为 manifest list。

编译参数如何影响镜像体积

除了 CGO，链接器参数也直接影响二进制大小。常用的两个是 -s 和 -w，它们分别去掉符号表和 DWARF 调试信息：

go build -trimpath -ldflags "-s -w" -o app .

-trimpath 会移除构建路径信息，既减小体积，也让构建结果更可复现。以一个中等规模的 HTTP 服务为例，未裁剪的二进制可能在 20MB 左右，加上 -s -w 后通常能降到 12～14MB；如果运行镜像从 debian:slim（约 75MB）换成 distroless/static（约 2MB）或 scratch，整体镜像体积可以从近百 MB 降到 15MB 以内。这些数字会随依赖变化，但量级关系是稳定的。

下面这张图把“编译选项 → 链接方式 → 运行镜像选择 → 最终体积”的因果关系串起来，便于在写 Dockerfile 前先做判断。

为容器运行而写的 Go 服务要点

编译方式确定后，服务本身还需要配合容器环境做一些调整。首先是信号处理：容器停止时，Docker 会向 PID 1 发送 SIGTERM，如果程序不处理，就会被强制 SIGKILL，导致连接被粗暴中断。使用 http.Server 的 Shutdown 配合 signal.NotifyContext 可以实现优雅退出：

ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGTERM, syscall.SIGINT)
defer stop()

srv := &http.Server{Addr: ":8080", Handler: mux}
go func() {
    if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
        log.Fatal(err)
    }
}()

<-ctx.Done()
shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
_ = srv.Shutdown(shutdownCtx)

其次是监听地址。容器内服务必须监听 0.0.0.0 而不是 127.0.0.1，否则端口映射无法访问。第三是日志输出到 stdout/stderr，而不是写文件，这样 docker logs 和日志采集才能正常工作。第四是配置通过环境变量注入，避免把配置烘焙进镜像。

一个可参考的构建与运行镜像组合

把上面的结论落到 Dockerfile 上，典型的多阶段构建如下。构建阶段使用完整 Go 镜像，运行阶段使用极小镜像：

FROM golang:1.22-bookworm AS builder
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
    go build -trimpath -ldflags "-s -w" -o /out/app ./cmd/server

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

这个组合的产物通常只有十几 MB，且不包含 shell，减少了被利用的风险。如果服务确实需要 CGO，把运行阶段换成 debian:bookworm-slim 并安装对应运行库即可，但要接受体积上升。

常见误区与排查线索

• 在 Alpine 上运行 glibc 二进制：表现为启动即退出，报 not found。用 file 和 ldd 确认链接类型，改用 Debian 系或重新静态编译。
• 忘记复制 CA 证书：HTTPS 请求报 x509: certificate signed by unknown authority。在 scratch/distroless 中补上证书文件。
• 监听 127.0.0.1：容器外无法访问。改为 :8080 或 0.0.0.0:8080。
• 忽略 SIGTERM：滚动更新时请求被中断。加入优雅退出逻辑并设置合理的 terminationGracePeriodSeconds。
• 把调试信息留在生产镜像：体积偏大。确认构建命令包含 -s -w 和 -trimpath。

把这些前置条件处理好，后续编写 Dockerfile、搭建 CI 流水线时就会顺畅很多：构建参数明确、运行镜像可预期、体积和启动行为都在掌控之中。