必须用多阶段构建且禁用CGO，运行阶段优先选alpine而非scratch；否则镜像常超800MB而二进制不足20MB。因CGO启用时依赖glibc，但alpine用musl libc，导致“no such file or directory”错误；静态编译（CGO_ENABLED=0）可彻底解决兼容性与体积问题。
直接结论：必须用多阶段构建，且 builder 阶段要禁用 CGO，运行阶段优先选 alpine 而非 scratch。 否则镜像体积大概率超 800MB，而实际二进制通常不到 20MB。
为什么 go build 出来的二进制在 alpine 里直接报 no such file or directory
这不是文件路径错了，是动态链接器不兼容。Go 默认启用 cgo，编译出的二进制依赖 glibc；但 alpine 用的是 musl libc，连 /lib64/ld-linux-x86-64.so.2 这个加载器都不存在。
- 临时解法：用
golang:alpine作 builder 镜像——但所有 cgo 依赖（如数据库驱动、图像处理库）必须全兼容 musl，实操中极易翻车 - 稳解：禁用 cgo，静态编译：
CGO_ENABLED=0 go build -a -ldflags '-s -w' -o app . -
-s去符号表，-w去调试信息，两者合起来常减 30%~50% 体积
COPY --from=builder 静默失败却找不到原因
常见现象：构建成功，但容器启动报 command not found 或 exec format error。根本原因是 builder 阶段没显式命名，或名字拼错。
-
FROM golang:1.22 AS builder中的builder是必须的标签，不是可选项 - 后续必须写
COPY --from=builder /app/app .，不能写--from=0（重构时阶段序号一变就断） - Docker 不会报错，只是把空目录复制过去——所以得靠
docker run -it <image> ls -l手动验证目标文件是否存在
该不该用 scratch 作为最终基础镜像
别急着上 scratch。它确实只有 0B，但 Go 程序在其中运行风险极高：
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
- 没有
/dev/null、/tmp、/proc，调用os.CreateTemp或os.UserHomeDir()会 panic - 无法接收
SIGTERM，kill -15后进程不退出，Kubernetes 认为 Pod 未优雅终止 - 日志输出可能卡住（标准输出底层依赖
/dev/stdout） - 真要用
scratch，得手动RUN mkdir -p /tmp && touch /dev/null——但RUN在scratch里根本不可用，只能靠外部挂载或放弃
推荐折中方案：FROM alpine:3.19，体积只比 scratch 多 2~3MB，但稳定得多。
CI 构建卡在 go mod download 怎么办
本地 go run 没问题，Docker 构建却超时，八成是 builder 阶段网络环境和 GOPROXY 不一致（比如公司内网私有代理没生效）。
- 加一步
go mod vendor，生成vendor/目录并提交到 Git - builder 阶段改用：
COPY go.mod go.sum vendor/ ./，再go build -mod=vendor -o app . -
-mod=vendor强制只读 vendor，彻底绕过网络和 GOPROXY 配置
这个细节容易被忽略：vendor 目录必须 git add 并 commit，否则 COPY vendor/ 会复制空目录，构建时直接报找不到包。
