必须统一go version与.go-version；团队需用goenv锁定版本（如1.21.13），ci显式指定，gobin置于path最前，go.mod初始化须用完整模块路径（如example.com/team/project-name），go.sum必须完整提交且不可手动编辑。
go version 和 .go-version 必须对齐
团队里有人用 go version 输出 go1.21.13，有人是 go1.22.3，看似只差一个小版本，实际会导致 go mod 解析行为不一致、泛型约束报错、gopls 启动失败。根本问题不是“能不能跑”，而是“谁在用什么规则解析模块”。
实操建议：
- 项目根目录放
.go-version，内容仅一行：1.21.13（LTS 推荐） - 所有人用
goenv（macOS/Linux）或 WSL +goenv（Windows），执行goenv local 1.21.13 - CI 脚本中显式写死
with: go-version: '1.21.13'，别依赖 actions/setup-go 的默认值 - 运行
go version和cat .go-version对比，不一致就立刻修正
GOBIN 必须在 PATH 最前，且禁止混用系统 bin
gofumpt -w . 没反应，或 gopls 报 command not found，大概率是 PATH 里有旧版工具顶替了你 go install 的那个。比如你装的是 $HOME/go/bin/gofumpt v0.5.0，但 /usr/local/bin/gofumpt v0.4.0 在 PATH 更靠前。
实操建议：
- 统一设
GOBIN=$HOME/go/bin，并在 shell 配置中确保它最左：export PATH="$HOME/go/bin:$PATH" - 验证：运行
which gofumpt和gofumpt -version，输出路径和版本必须匹配 - 禁止
sudo go install或往/usr/local/bin写工具——污染系统，且无法随项目版本锁定
go.mod 初始化必须指定完整模块路径
用 go mod init 不带参数，本地可能能 build，但别人 clone 后直接报错：import "xxx" is a program, not an importable package。这是因为模块路径为空，所有导入都失去解析依据。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
实操建议：
- 初始化必须写全路径：
go mod init example.com/team/project-name，与 Git 仓库地址严格一致 - 路径全小写、无空格、无特殊字符；私有域名需确保 DNS 可解析，否则
go get会 fallback 到 HTTPS 探测失败 - 禁用
go mod init .或go mod init $(basename $PWD)—— 跨仓库迁移时极易出错 - 检查
go.mod第一行是否为module example.com/team/project-name，不是就重做
go.sum 必须提交，且禁止手动编辑
go build 报 verifying github.com/xxx@v1.2.3: checksum mismatch，往往是因为有人删了 go.sum 里的某几行“看着冗余”的校验和。这不是配置文件，是 Go 构建时强制校验的快照。
实操建议：
-
go.sum和go.mod一样，必须完整提交到 Git，不可加进.gitignore - 依赖变更后只运行
go mod tidy，它会自动增删go.sum行；别用编辑器排序、合并或删行 - CI 中加
go mod verify步骤，早于go test和go build，提前暴露校验失败 - 若遇校验失败，先查
GOPROXY和GOPRIVATE配置，而不是加GOINSECURE绕过
真正难的从来不是“怎么装 Go”，而是让所有人同一时刻、同一路径、同一版本、同一命令触发同一行为。版本、路径、校验、工具链——四个点里只要一个漂移，协作成本就会指数上升。这些不是“可选规范”，是协作的水位线。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
