Go 应用 Docker 容器化分步指南

本文依据官方文档整理，未执行运行验证或性能基准。代码片段展示局部用法，业务函数、数据和环境需按项目补齐；版本与配置以所引文档为准。

直接回答：Go 容器化常用多阶段构建——第一阶段 golang 官方镜像编译出静态二进制，第二阶段 scratch/distroless 极简镜像只放二进制，最终镜像可小到十几 MB。开发期用 Compose 编排应用与数据库，生产期应用镜像与数据库、配置和密钥分别管理。

为什么 Go 特别适合容器化

纯 Go 程序通常可以编译成单个静态可执行文件，Go 运行时也包含在二进制中。使用 CGO 或外部动态库时不能假定完全静态；证书、时区、模板与配置仍须按应用需要提供。

多阶段 Dockerfile

# 编译阶段
ARG GO_VERSION
FROM golang:${GO_VERSION}-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o server ./cmd

# 运行阶段
FROM scratch
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=builder /app/server /server
USER 65532:65532
EXPOSE 8080
ENTRYPOINT ["/server"]

构建时通过 --build-arg GO_VERSION 传入项目验证且仍受维护的 Go 版本，发布镜像再固定摘要。示例假定 main 包位于 ./cmd，且 go.sum 已生成。要点：CGO_ENABLED=0 禁用 CGO，适用于不依赖 C 库的普通可执行程序；-ldflags="-s -w" 去符号表再瘦一圈；go.mod/go.sum 单独 COPY 利用层缓存。

scratch 太空不好调试？换 gcr.io/distroless/static——含 CA 证书与时区数据，几 MB 代价换可用性。

Compose 编排与开发工作流

services:
  app:
    build: .
    ports: ["8080:8080"]
    depends_on: [db]
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set a local development password}
    volumes: ["pgdata:/var/lib/postgresql/data"]
volumes:
  pgdata:

开发期配 air/gow 热重载容器；生产期直接用上面极简镜像。可另增开发阶段后用 --target 选择；上面的 Dockerfile 本身未包含热重载阶段。Compose 仅示意本地编排：应用还需配置数据库地址 db:5432，depends_on 默认只控制启动顺序，不保证数据库就绪，应用需重试或配置健康检查。生产数据库需独立备份和权限控制。

验证 Compose 启动顺序时，让应用记录数据库连接失败、重试和成功的日志，并输出到 stdout/stderr。接入观测云可参考 DataKit 日志采集指南，确认容器重建后仍能查到上一实例的启动错误，再判断重试策略是否有效。

常见问题（FAQ）

Q：scratch 镜像里 HTTPS 请求报证书错误？
A：scratch 没有 CA 证书。COPY 编译阶段的 /etc/ssl/certs/ca-certificates.crt 进去，或直接用 distroless。

Q：CGO 必须关吗？
A：依赖必须调用 C 的驱动或库时不能关；net/os/user 通常也有纯 Go 实现，并非导入它们就必须启用 CGO——此时运行基底换 alpine/debian 并装对应 libc。

Q：镜像还能更小吗？
A：先排除不需要的构建产物并采用多阶段镜像。二进制压缩的收益、启动开销与安全扫描兼容性需自行评估，不能保证固定比例。

官方参考

• 官方文档 1
• 官方文档 2

资料核对日期：2026-09-29。

延伸阅读

• Go 1.24 新特性详解