必须统一Go环境，锁定Go版本（.go-version文件）、GOBIN路径（前置PATH）、GOPROXY代理（+go.sum）及工具链（tools.go），四者缺一不可。

团队内部 Go 环境不统一，90% 的构建失败和“在我机器上能跑”问题都源于此——必须从 Go 版本、工具链、依赖解析三处同时卡死。

Go 版本必须锁定在 .go-version 文件里

不同 Go 版本可能让 go build 产出不兼容的二进制，或导致 gopls 语言服务崩溃。LTS 版本（如 1.21.x）不是可选项，是底线。

• 所有成员根目录下放一个 .go-version 文件，内容仅一行：1.21.10（具体 patch 号要写死）
• 用 goenv 或 gvm 读取该文件自动切换版本；CI 中用 actions/setup-go@v5 时显式传入 go-version: '1.21.10'，不能写 1.21 或 latest
• 禁止任何人手动执行 brew install go 或下载安装包——这会绕过版本控制，且无法被 CI 复现

GOBIN 必须前置到 PATH 最前面

本地安装的工具（如 gofumpt、golangci-lint）若被系统 PATH 里旧版覆盖，pre-commit 钩子就会静默失效。

• 统一设 GOBIN=$HOME/go/bin，并在 shell 配置（~/.zshrc 或 ~/.bash_profile）中确保它出现在 PATH 最前：export PATH="$GOBIN:$PATH"
• 验证方式：运行 which gofumpt，输出必须是 /home/xxx/go/bin/gofumpt，而非 /usr/local/bin/gofumpt
• Windows 用户注意：PowerShell 的 $env:PATH 设置顺序同样关键，不要依赖 GUI 环境变量编辑器

依赖解析必须靠 GOPROXY + go.sum 双保险

不设代理，go mod download 会直连 GitHub，超时或限速直接中断；不提交 go.sum，不同机器拉取的同一 commit 可能哈希不一致。

Golang Spf13 Viper

Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。

下载

立即学习“go语言免费学习笔记（深入）”；

• 团队强制设置：export GOPROXY=https://proxy.golang.org,direct；私有模块加 GOPRIVATE=git.company.com
• go.mod 和 go.sum 必须一起提交，且 go.sum 不允许手工编辑——它由 go mod download 自动生成
• CI 流水线第一步必须跑 go mod verify，失败则立即终止；本地开发也建议 alias gobuild='go mod verify && go build'

工具链必须固化到 tools.go 而非全局安装

用 go install 全局装工具，版本一升级全队崩；靠 tools.go 锁定，才能保证 make lint 在所有人机器上跑的是同一版 golangci-lint。

• 项目根目录建 tools.go，内容只含空导入和构建约束：

  //go:build tools
  // +build tools
  
  package tools
  
  import (
  	_ "github.com/golangci/golangci-lint/cmd/golangci-lint"
  	_ "golang.org/x/tools/cmd/goimports"
  )

• 用 go mod vendor 或 go run tools.go 安装，工具二进制会落到 $GOBIN 下，但版本由 go.sum 控制
• 别信 “我本地 golangci-lint --version 是 v1.54.2 就行”——必须确认它来自 tools.go 所声明的 commit，否则 CI 里跑的是 v1.55.0，规则可能已变

最易被忽略的点：GOBIN 路径和 GOPROXY 设置看似简单，但一旦漏掉任一环节，就会出现“本地通过、CI 报错、同事环境莫名失效”的三角故障。统一不是靠文档喊口号，而是靠每个环节的硬性拦截——版本文件、PATH 顺序、go.sum 提交、tools.go 声明，缺一不可。