必须统一 Go 版本（如 1.21.13）、GOBIN 路径置于 PATH 最前、构建封装进 Makefile、go.mod 与 go.sum 必提交且禁用未清理的 replace，否则导致 CI 失败、IDE 错乱、工具版本冲突及依赖不一致。
go version 和 .go-version 必须对齐
团队里有人用 go version 1.21.13，有人用 1.22.3，CI 就会莫名其妙失败——不是代码问题，是 Go 自身行为变了。
1.22+ 默认启用 module-aware 模式，gopls v0.14+ 依赖它；而 1.21 可能 fallback 到 GOPATH 模式，导致 IDE 提示错乱、go mod tidy 行为不一致。泛型里的 ~A 类型约束在 1.22 才完全稳定，低版本直接报错。
- 项目根目录放
.go-version，内容只有一行：1.21.13（LTS 推荐） - 成员统一用
goenv（macOS/Linux）或 WSL +goenv（Windows），执行goenv local 1.21.13 - CI 脚本中显式写死：
with: go-version: '1.21.13'，别信默认值
GOBIN 必须在 PATH 最前，且禁止混用系统 bin
gofumpt -w . 没反应？gopls 启动失败提示 “command not found”？大概率是 PATH 里有旧版工具抢跑了。
你用 go install golang.org/x/tools/cmd/gofumpt@v0.5.0 装到 $HOME/go/bin/gofumpt，但 /usr/local/bin/gofumpt（v0.4.0）在 PATH 里更靠前，结果调的永远是旧版。
立即学习“go语言免费学习笔记（深入）”；
- 统一设
GOBIN=$HOME/go/bin，并在 shell 配置中确保它出现在PATH最左侧：export PATH="$HOME/go/bin:$PATH" - 执行
which gofumpt和gofumpt -version验证是否命中你go install的那个 - 严禁
sudo go install或往/usr/local/bin写工具——污染系统、无法版本锁定
编译命令必须封装进 Makefile，禁用裸写 go build
直接敲 go build -o ./bin/app ./cmd/app 看似快，但在团队里等于埋雷：不同人加的 -ldflags 不同、GOOS/GOARCH 不一致、甚至有人漏掉 -trimpath 导致二进制里泄露本地路径。
更麻烦的是，有人本地跑通，CI 却因缺少 -buildmode=pie 被安全扫描拦截。
- 所有构建逻辑收口到
Makefile，例如：make build对应完整命令链 - 关键参数固化：
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o ./bin/app ./cmd/app - 禁止在 PR 中出现裸
go build命令；CI 流程强制走make build
go.mod 和 go.sum 必须提交，replace 仅限临时调试
有人为调试本地子模块，在 go.mod 加了 replace github.com/team/lib => ../lib，忘了删就提交——CI 构建直接报错：cannot find module providing package。
go.mod 是依赖声明，go.sum 是校验锁，两者缺一不可。不提交 go.sum，别人 go mod download 下来的可能是被篡改过的包。
-
go.mod和go.sum必须提交 Git，且每次go mod tidy后重新生成go.sum -
replace只允许出现在本地开发分支，且必须加注释说明用途和预计移除时间 - CI 流程中加入
go mod verify，防止go.sum被绕过或篡改
真正卡住协作质量的，从来不是语法多难，而是那些看似“能跑就行”的细节：PATH 顺序、go.sum 是否提交、replace 有没有清理干净。这些地方一旦松动，问题就藏在日志最底下，等上线才浮出来。
