多阶段构建是必须的，需用golang镜像构建并禁用CGO、设置GOOS=linux、剥离符号表，再复制二进制到alpine或scratch镜像；否则因libc不兼容或路径权限问题导致exec format error或No such file or directory。
go build 生成的二进制必须能在目标镜像中运行，否则容器启动就直接报 exec format error 或 No such file or directory
多阶段构建是必须的，不是可选项
单阶段用 golang:alpine 直接 go build 然后 CMD ["./app"] 看似简单，但实际会把 Go 工具链、调试符号、CGO 动态依赖全打包进去。最终镜像可能超过 300MB，且存在严重安全风险。
真正可用的生产写法必须分两层：
- 构建阶段用完整 Go 环境（如
golang:1.21-alpine），执行go mod download和go build - 运行阶段用纯
alpine:3.18或scratch，只 COPY 编译好的二进制和必要配置
关键编译参数不能漏：
立即学习“go语言免费学习笔记（深入）”；
-
CGO_ENABLED=0：禁用 CGO，避免运行时依赖 libc -
GOOS=linux：确保目标系统是 Linux（容器默认） -
-ldflags="-w -s"：剥离调试信息和符号表，体积减少 30%～50%
示例片段：
FROM golang:1.21-alpine AS builder WORKDIR /app COPY go.mod go.sum . RUN go mod download COPY . . RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-w -s" -o gin-app . <p>FROM alpine:3.18 RUN apk --no-cache add ca-certificates tzdata WORKDIR /root COPY --from=builder /app/gin-app . COPY --from=builder /app/configs ./configs USER nobody EXPOSE 8080 ENTRYPOINT ["./gin-app"]
alpine 镜像里跑不起来？先查 libc 兼容性
alpine 用的是 musl libc，而默认 go build（尤其没设 CGO_ENABLED=0）会链接 glibc。两者不兼容，容器一启动就报错：
standard_init_linux.go:228: exec user process caused: no such file or directory
这不是路径错了，是动态链接器找不到。验证方法很简单：
ldd ./gin-app | grep "not found"
如果看到 libc.so.6，说明你没关 CGO。
解决方式只有两个：
使用 Python 脚本下载 Docker 镜像并打包为 tar 文件。用户说“下载镜像”“拉取镜像”“pull xxx”“帮我下载 nginx 镜像”等时触发。支持 SOCKS5 代理直连（推荐）和国内镜像站加速两种模式。
- 强制
CGO_ENABLED=0（推荐，静态链接） - 改用
debian:slim基础镜像（体积翻倍，不推荐）
另外注意：某些 Gin 中间件（比如用到 net/http/pprof 或调系统命令的）在 scratch 镜像里会缺 /dev/pts 或 /proc，这时得回退到 alpine 并补 apk add 对应工具。
配置文件和日志路径别硬编码进二进制
很多新手把 configs/config.yaml 路径写死在代码里，然后 COPY 到镜像任意位置，结果运行时报 open configs/config.yaml: no such file or directory。
Gin 应用启动前应明确配置加载逻辑：
- 使用相对路径时，以
os.Getwd()为准，但容器里WORKDIR才是当前工作目录 - 更稳妥的方式是通过环境变量传入路径，比如
CONFIG_PATH=/configs/config.yaml - 日志文件路径同理，不要写
./logs/app.log，改用/var/log/gin-app/app.log并确保目录可写（chown nobody:nogroup /var/log/gin-app）
常见错误组合：
-
COPY configs/ /configs/但代码里读的是./configs/ -
USER nobody后没给/configs目录赋读权限 -
ENTRYPOINT没指定工作目录，导致相对路径解析失败
EXPOSE 不等于端口映射，ENTRYPOINT 比 CMD 更可靠
EXPOSE 8080 只是文档性声明，不影响实际网络行为。真正决定监听端口的是 Gin 代码里的 r.Run(":8080") —— 必须和容器暴露端口一致，否则健康检查失败。
更关键的是启动指令：
- 用
CMD ["./gin-app"]时，如果 Dockerfile 上层有父镜像定义了CMD，会被覆盖或拼接，行为不可控 -
ENTRYPOINT ["./gin-app"]是强制入口，不会被docker run后面的参数覆盖（除非显式加--entrypoint）
顺带提醒：Gin 默认绑定 0.0.0.0:8080，不是 127.0.0.1:8080。后者在容器里根本收不到外部请求。
最后一点容易被忽略：K8s 的 livenessProbe 如果用 httpGet，路径必须是 Gin 实际注册的路由（比如 /healthz），而不是根路径 / —— 很多 demo 里没配健康接口，probe 一直失败，滚动更新就卡住。
