不能直接用 FROM golang:alpine 做生产镜像，因其包含完整编译环境，导致镜像体积大（超500MB）、存在安全风险；应采用多阶段构建，分离编译与运行阶段，使用 golang:1.22-slim 编译、distroless/static 运行，并设 CGO_ENABLED=0 实现静态链接。
为什么不能直接用 FROM golang:alpine 做生产镜像
因为这样会把整个 Go 编译环境打进镜像，最终镜像体积大（常超 500MB），且包含不必要的工具链和源码，存在安全风险。生产环境该用多阶段构建，编译和运行彻底分离。
典型错误是只写一个 FROM golang:1.22，然后 COPY . . + RUN go build + ENTRYPOINT —— 这样镜像里既有 go 命令、$GOROOT，又有调试符号、测试依赖，根本不是“只跑二进制”的最小化镜像。
- 编译阶段用
golang:1.22-alpine或golang:1.22-slim（推荐后者，兼容性比 Alpine 更稳） - 运行阶段必须用
FROM scratch或FROM gcr.io/distroless/static（更安全）或至少FROM alpine:latest（轻量但需手动清理） - 如果项目用了 cgo（比如依赖 SQLite、OpenSSL），就不能用
scratch，得切回alpine或debian:slim并开启CGO_ENABLED=1
Dockerfile 多阶段构建怎么写才不踩坑
核心就两段：build 阶段编译出静态二进制，final 阶段只 COPY 二进制和必要配置。关键点不在语法，而在路径、权限和环境变量的传递是否干净。
下面这个结构经实战验证，覆盖绝大多数纯 Go Web 服务（如 Gin、Echo、net/http）：
立即学习“go语言免费学习笔记（深入）”；
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
FROM golang:1.22-slim 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 /app/server . <p>FROM gcr.io/distroless/static WORKDIR /root/ COPY --from=builder /app/server . EXPOSE 8080 USER nonroot:nonroot ENTRYPOINT ["./server"]
-
CGO_ENABLED=0是默认关闭 cgo 的关键，避免动态链接；若必须开，请换FROM golang:1.22-alpine编译，并用alpine:latest运行 -
-a -ldflags '-extldflags "-static"'强制静态链接，防止 final 镜像缺 libc 等依赖 - 别用
ADD，统一用COPY；别在 final 阶段RUN apt-get—— distroless 没包管理器 -
USER nonroot:nonroot必须加，否则容器以 root 运行，K8s 会拒绝调度（除非显式允许）
Go 服务启动失败常见报错和定位方法
镜像能 build 成功 ≠ 能跑起来。最常卡在：端口没暴露、文件权限不对、配置路径硬编码、或 os.Getwd() 在容器里返回空/错路径。
遇到 standard_init_linux.go:228: exec user process caused: no such file or directory，不是二进制丢了，而是它依赖的动态库找不到（cgo 开了但运行镜像没装 musl/glibc）；遇到 permission denied，大概率是二进制没加可执行位，或 COPY 时丢失了权限（Docker 默认不保留 chmod，得用 COPY --chmod=755）。
- 本地快速验证 final 镜像：运行
docker run --rm -it <image> ls -l ./server，确认权限是-rwxr-xr-x - 检查二进制是否静态：
docker run --rm -it <image> ldd ./server，返回not a dynamic executable才对 - 日志没输出？加
ENV GODEBUG=schedtrace=1000或在 main 入口前加log.Println("starting...")，排除启动即 panic - 读不到
config.yaml？别用相对路径./config.yaml，改用filepath.Join(os.Getenv("PWD"), "config.yaml")或挂载绝对路径
如何让 Docker 镜像支持热重载开发（非生产用）
开发时不想每次改代码都 docker build，可以用 volume 挂载源码 + 容器内实时编译。但注意：不要在 production Dockerfile 里写 go run，那是反模式。
推荐方案：单独建 docker-compose.dev.yml，复用 builder 镜像，用 air 或 fresh 监听文件变化：
services:
app:
build:
context: .
dockerfile: Dockerfile.dev
volumes:
- ".:/app"
- "/app/go/pkg"
working_dir: /app
command: air
-
Dockerfile.dev只需FROM golang:1.22-slim+WORKDIR /app+RUN go install github.com/cosmtrek/air@latest - 挂载
/app/go/pkg是为了复用 module cache，加速下次 build - 别把
go.mod单独挂载——会导致 host 和 container 的 module checksum 冲突 - air 的配置文件
.air.toml必须放在项目根目录，且root设为.，否则监听失效
真正上线前，一定要用正式 Dockerfile 构建并跑一次集成测试，开发镜像和生产镜像不该共用同一份构建逻辑。
