GitHub Actions中setup-go版本不匹配会导致go mod download失败，主因是Go版本与go.mod声明的版本不兼容，需显式指定相同主版本并用go version验证；CGO_ENABLED=0会改变DNS解析行为，-race测试在CI中更具概率性，Docker构建需注意输出路径和权限。
GitHub Actions中setup-go版本不匹配导致go mod download失败
CI里go mod download报错“no required module provides package”，大概率是actions/setup-go装的Go版本和项目go.mod声明的版本不兼容。比如go.mod写的是go 1.22，但workflow里用了go-version: '1.21'，模块解析器会拒绝加载新语法特性。
- 检查
go.mod第一行的go x.y，然后在setup-go中显式指定相同主版本（如1.22.x），不要用latest或模糊版本号 - 加一步
run: go version确认实际生效版本，避免被缓存或平台默认版本覆盖 - 若项目依赖较新的标准库特性（如
net/netip或slices包），必须用≥对应引入版本的Go，否则go build会静默跳过或编译失败
交叉编译时CGO_ENABLED=0引发DNS解析异常
设CGO_ENABLED=0生成纯静态二进制很常见，但net包的DNS解析逻辑会从libc切换到Go内置实现，导致内网环境无法解析私有域名——这不是bug，而是行为差异。
- 测试阶段务必在目标环境网络下跑
go test -v ./...，不能只依赖本地loopback测试 - 若必须用
CGO_ENABLED=0，可通过GODEBUG=netdns=go强制走Go resolver，或提前用dig验证DNS配置是否被容器/宿主机劫持 - 真正需要cgo（如sqlite、openssl）时，别硬关
CGO_ENABLED，改用golang:1.22-slim镜像并安装gcc和libc6-dev，比折腾musl兼容更可靠
go test -race在CI中频繁失败但本地正常
go test -race在CI里爆data race而本地不报，不是环境问题，是竞态本身具有概率性——CI调度更激进、CPU资源更紧张，更容易触发临界条件。
- 绝不能把
-race仅作为可选开关；它必须出现在所有CI测试命令中，且失败即终止 - 避免用
time.Sleep做同步，race detector对sleep无感知，但goroutine仍可能并发访问共享变量 - 检查第三方依赖是否含已知竞态（如老版本
golang.org/x/net/http2），升级到v0.22.0+或替换为net/http原生实现 - 若测试用
sync.WaitGroup，确保Wait()调用在所有Add()之后，且没有goroutine启动后立即return导致计数未减
Docker多阶段构建时go build输出路径混乱
很多Dockerfile在build阶段用go build -o app .，结果二进制落在/workspace/app，却忘了在final stage用COPY --from=builder /workspace/app /app，导致镜像里没程序可运行。
立即学习“go语言免费学习笔记（深入）”；
- 统一用绝对路径输出：
go build -o /app/main ./cmd/main，避免相对路径受WORKDIR影响 - final stage用
FROM scratch或distroless时，别漏掉COPY --chmod=755，否则即使文件存在也会因权限不足无法执行 - 如果项目有多个main包（如CLI工具+HTTP服务），用
go build -o /app/cli ./cmd/cli和go build -o /app/server ./cmd/server分开构建，别指望单个go build能自动识别
