必须用 go.mod 和 go.sum 管理依赖，禁止手动修改 go.sum；统一 Go 版本需 .go-version 文件 + CI 校验；GOROOT 应指向官方安装路径；编辑器配置以项目级 .vscode/settings.json 为准。
Go 项目必须用 go.mod，且禁止手动修改 go.sum
团队协作中最大的环境不一致来源，是依赖版本漂移。只要没启用模块（即没有 go.mod），go get 就会写入 $GOPATH/src，不同人本地的 commit hash、分支、甚至私有 fork 都可能被拉取，导致构建结果不可复现。
强制所有项目初始化时运行：
go mod init example.com/myapp并立即提交生成的
go.mod 和 go.sum。后者记录每个依赖的校验和，CI 或新成员 go build 时会自动校验——若有人绕过 go mod 直接改 vendor 或替换源码，构建会直接失败，错误信息类似：verifying github.com/some/pkg@v1.2.3: checksum mismatch
- 禁止手动编辑
go.sum：它应完全由go mod tidy/go build自动生成 - 升级依赖必须走
go get -u ./...或go get some/pkg@v1.4.0，再跑go mod tidy - 私有模块需配置
GO_PRIVATE环境变量，避免被 proxy 重定向（例如：export GO_PRIVATE="git.internal.company.com/*"）
统一 Go 版本靠 go version + .go-version 文件
Go 官方不提供跨平台的版本管理工具，但团队必须锁定主版本（如 1.21）和补丁版本（如 1.21.6）。仅靠文档或口头约定毫无约束力。
推荐组合方案：go version 检查 + .go-version 声明 + CI 强制拦截：
立即学习“go语言免费学习笔记（深入）”；
- 在项目根目录放纯文本文件
.go-version，内容为1.21.6（不含v） - 开发机安装
godotenv或用 shell 脚本读取该文件并比对go version输出；不匹配则报错退出 - CI 流水线第一步执行：
go version | grep -q 'go1\.21\.6' || (echo "Go version mismatch" && exit 1)
注意：Go 1.21+ 的泛型、io.ReadSeeker 行为变更等，都可能让 1.21.5 下能编译的代码在 1.21.7 报错——补丁版本也得锁死。
GOPATH 不再需要全局设置，但 GOROOT 必须由安装包控制
Go 1.16+ 默认启用 GO111MODULE=on，GOPATH 对构建已无影响（仅用于存放 go install 的二进制和缓存）。强行统一 GOPATH 反而增加路径冲突风险。
真正要管的是 GOROOT：它指向 Go 安装根目录，若混用不同来源的 Go（如 Homebrew、SDKMAN、手动解压），go tool compile 行为可能不一致。
- 禁止用
brew install go后再手动下载官方 tar.gz 覆盖——Homebrew 的 patch 可能与标准版不兼容 - 推荐所有成员从 https://www.php.cn/link/81836b7cd16991abb7febfd7832927fd 下载同一架构的 tar.gz（如
go1.21.6.linux-amd64.tar.gz），解压到固定路径（如/opt/go），然后设GOROOT=/opt/go - 验证方式：
echo $GOROOT && ls $GOROOT/src/runtime/internal/sys/zversion.go
—— 文件存在且内容含对应版本号即正确
编辑器配置靠 gopls + 统一 settings.json 片段
VS Code 是 Go 团队事实标准编辑器，核心能力来自 gopls（Go Language Server）。但默认配置常导致符号跳转失败、格式化风格不一致。
在项目根目录建 .vscode/settings.json，内容如下：
{
"go.gopath": "",
"go.goroot": "/opt/go",
"go.toolsManagement.autoUpdate": true,
"go.formatTool": "gofumpt",
"go.lintTool": "revive",
"gopls": {
"build.directoryFilters": ["-node_modules"],
"analyses": {
"shadow": true,
"unnecessaryElse": true
}
}
}
-
go.gopath留空：避免误用旧式 GOPATH 模式 -
go.formatTool设为gofumpt（非默认gofmt），它强制更严格的空白和括号规则，减少 PR 中无意义的格式争议 -
gopls.analyses开启静态检查项，问题直接标红，比后期 CI 报错更早暴露 - 所有成员必须禁用本地全局 Go 插件设置，只认项目级
.vscode/settings.json
真正难统一的不是工具链，而是开发者是否愿意删掉自己习惯的快捷键、插件和终端 alias。环境配置文档写得再细，不如一条 make setup 脚本自动拉取正确 Go、安装 gofumpt、校验 go.sum 并提示重启编辑器——但脚本本身得先放进仓库里。
