应使用多阶段构建而非 golang:latest，因其体积大、含冗余工具链、默认 root 运行且未清理缓存；必须设 CGO_ENABLED=0 并静态编译，避免动态链接 libc；最终镜像需创建非特权用户并正确设置目录权限。
为什么不用 FROM golang:latest 直接运行你的应用
很多新手直接用 golang:latest 作为基础镜像，把源码 COPY 进去再 go run main.go 启动——这在开发阶段看似能跑，但上线后会出问题。该镜像体积大（>1GB），包含完整 Go 工具链和 C 编译器，而生产环境只需要可执行二进制文件；更重要的是，它默认以 root 用户运行，违反最小权限原则，且未清理构建缓存，镜像层臃肿、安全扫描通不过。
多阶段构建中 CGO_ENABLED=0 必须设为 0
Go 默认启用 CGO，依赖系统 libc（如 glibc 或 musl），导致编译出的二进制无法在 alpine 等精简镜像中运行。即使你用 debian:slim，也建议显式关闭：
FROM golang:1.22-alpine AS builder WORKDIR /app COPY go.mod go.sum ./ RUN go mod download COPY . . RUN CGO_ENABLED=0 GOOS=linux go build -a -ldflags '-extldflags "-static"' -o myapp . FROM alpine:3.19 COPY --from=builder /app/myapp /usr/local/bin/myapp CMD ["myapp"]
-
CGO_ENABLED=0是硬性要求，否则二进制可能动态链接宿主机 libc，容器启动报no such file or directory -
GOOS=linux避免本地 macOS/Windows 构建时产生不兼容二进制 -
-a -ldflags '-extldflags "-static"'强制静态链接，进一步消除运行时依赖
Dockerfile 中 WORKDIR 和 USER 设置影响挂载与权限
Go 应用常需读写配置文件或日志目录，若镜像里没提前创建路径或用户权限不对，容器一启动就 panic。比如用 alpine 基础镜像，默认没有非 root 用户，而 Kubernetes 默认以 UID 65532 运行容器，会导致 open /data/config.yaml: permission denied。
- 在最终镜像中添加非特权用户：
RUN addgroup -g 1001 -f appgroup && adduser -S appuser -u 1001 - 确保数据目录可写：
RUN mkdir -p /data && chown appuser:appgroup /data - 切换用户：
USER appuser:appgroup，且该行必须在COPY之后、CMD之前 - 避免在
ENTRYPOINT中用su切换用户——它无法正确传递信号，导致 SIGTERM 无法终止进程
如何验证镜像是否真的“干净”
构建完别急着推 registry，先本地检查：运行容器并进入 shell，确认没有多余工具、没有残留源码、二进制不依赖动态库。
立即学习“go语言免费学习笔记（深入）”；
- 检查体积：
docker images | grep your-app，理想值应 - 检查依赖：
docker run --rm -it your-app:latest ldd /usr/local/bin/myapp，输出应为not a dynamic executable - 检查内容：
docker run --rm -it your-app:latest sh -c 'ls -la /app || echo "/app not found"'，确认源码未被意外 COPY 进最终镜像 - 测试信号转发：
docker run -d --name testapp your-app:latest，然后docker kill -s TERM testapp，观察日志是否正常打印 shutdown 日志
最易被忽略的是信号处理——Go 默认不自动响应 SIGTERM，得自己注册 os.Signal，否则 k8s 的 preStop 钩子会超时强制 kill，造成请求中断。
