必须用 goenv + .go-version 锁定 Go 版本，显式设置 GOOS/GOARCH，go.mod 的 go 指令需与之严格对齐，禁用 go get -u，统一 gopls + .golangci.yml 配置，CI 中校验依赖树一致性。
用 goenv + GOOS/GOARCH 锁定版本和构建目标
团队里最常出问题的不是代码逻辑，而是本地 go version 不一致导致 go mod download 结果不同、go test 行为差异，甚至 go build 产出二进制在 CI 上跑不起来。必须从源头控制 Go 版本和交叉编译环境。
- 统一用
goenv管理 Go 版本（不用系统包管理器或手动解压），并在项目根目录放.go-version文件，例如内容为1.21.6 - 所有构建脚本（Makefile / CI YAML）显式设置
GOOS=linux GOARCH=amd64，避免开发者本地 macOS 上跑出darwin二进制还提交到部署清单里 - CI 流水线中禁止使用
go version输出做条件判断——它受GOROOT和PATH影响太大；改用goenv version或直接读.go-version
go.mod 里不能省略 go 指令且必须与 .go-version 严格对齐
很多人以为 go mod init 自动生成的 go 1.21 只是提示，其实它会影响泛型解析、constraints 语法支持、甚至 embed 行为。Go 1.21 和 1.22 对 type alias 的处理就不同。
- 执行
go mod edit -go=1.21.6显式写死小版本（不是只写1.21），然后git add go.mod - CI 中加检查：用
awk '/^go / {print $2}' go.mod提取版本，和cat .go-version对比，不一致就exit 1 - 禁止用
go get -u升级依赖——它会悄悄升级go指令值；升级依赖一律走go get example.com/pkg@v1.2.3或go mod tidy后人工核对
编辑器配置必须通过 .golangci.yml + gopls 统一 lint 和格式化行为
VS Code 的 gopls、GoLand 的内置分析器、命令行 golint（已归档）和 revive 默认行为各不相同。靠“大家装同一个插件”解决不了问题，得靠配置驱动。
- 项目根目录放
.golangci.yml，启用govet、errcheck、staticcheck，禁用golint（已废弃）和deadcode（go vet已覆盖） - 强制所有编辑器使用
gopls，并在其配置中指定"build.experimentalUseInvalidFiles": false，否则会误报未保存文件的错误 - 格式化统一用
go fmt（不是gofmt命令行），因为gopls调用的就是它；禁止配置编辑器调用goimports——它会自动增删 import，和go mod tidy冲突
CI 流水线里用 go list -m all 校验依赖树一致性
本地 go mod tidy 成功不代表 CI 也一致——可能因为 GOPROXY 缓存、私有模块权限、或 replace 规则没提交。最可靠的验证方式是比对完整模块列表。
- CI 构建前运行：
go list -m all | sort > deps-ci.txt
，再和预生成的deps-expected.txt（由主干分支定期更新）用diff对比 - 禁止在
go.mod中使用replace指向本地路径（如replace example.com/pkg => ../pkg），这类规则不会被go list -m all识别，会导致本地能过 CI 报错 - 私有模块必须走
git+ssh或带认证的https，并在 CI 中注入~/.netrc或git config，确保go mod download不因权限失败而 fallback 到不一致的 proxy 缓存
真正难的不是写清楚规范文档，而是让 go build 在任何人的机器上、任何时间点、任何分支上，输出完全相同的字节流——这要求版本、模块、构建参数、环境变量四个维度全部锁定。少一个，早晚有人在周五下午三点发现「我本地好好的」。
