Go版本必须匹配团队.go-version文件且GO111MODULE必须为on，否则会fallback至GOPATH模式导致依赖解析错乱；需执行go env -w GO111MODULE=on并确认项目根目录存在go.mod文件。
确认 Go 版本和模块模式是否启用
新成员装完 Go 后，go version 输出必须匹配团队 .go-version 文件（如 1.21.13），且 GO111MODULE 必须为 on —— 这是现代 Go 项目运行的前提。如果 go env GO111MODULE 返回 auto 或 off，说明仍可能 fallback 到 GOPATH 模式，导致 go mod 命令异常或依赖解析错乱。
- 执行
go env -w GO111MODULE=on强制启用模块模式 - 检查
go.mod是否存在于项目根目录；若无，运行go mod init example.com/project初始化（注意替换为实际 module path） - 禁止手动设置
GOPATH干扰模块行为；如需兼容旧工具，仅保留GOBIN指向$HOME/go/bin，并确保该路径在PATH最前
安装并验证团队指定的工具链
工具不是“装了就行”，而是要版本对、路径对、能被 make 正确调用。团队固化在 tools.go 中的工具（如 gofumpt、golangci-lint）必须通过 go install 安装，而非系统包管理器或二进制下载——后者极易版本错配或权限冲突。
- 运行
go run tools.go（或go mod download && go install ./tools）触发安装 - 验证
gofumpt -version和golangci-lint --version输出是否与.golangci.yml中声明的 linter 兼容 - 检查
$HOME/go/bin下是否存在对应可执行文件，且which gofumpt返回该路径 - 若
make fmt报错command not found，大概率是GOBIN未加入PATH，或 shell 配置未重载（如source ~/.zshrc）
初始化 pre-commit 并跑通本地 CI 流程
pre-commit 不是摆设，它是第一道防线。它失败意味着格式、lint 或测试没过，直接阻断提交 —— 但很多新人卡在钩子没生效或报错看不懂。
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 先确认已安装
pre-commit：运行pip install pre-commit（推荐全局 pip，不建议用 brew 或 conda 管理） - 在项目根目录执行
pre-commit install，而非pre-commit install --hook-type commit-msg等冗余参数 - 首次运行
git commit会自动触发make fmt和make lint；若报exit code 1，看错误里具体是哪个命令失败（常见是golangci-lint检出SA1019等禁用 API） - 本地跑
make ci应完全等价于 CI 流水线行为；若失败而 CI 成功，优先查go version和golangci-lint版本是否一致
Docker 开发容器启动失败的三个高频原因
远程开发环境用 Docker 起不来，90% 不是镜像问题，而是本地配置或挂载细节没对齐。
立即学习“go语言免费学习笔记（深入）”；
-
Dockerfile中COPY go.mod .后缺少RUN go mod download，导致COPY . .时依赖未缓存，构建超时或失败 - 本地
docker-compose.yml挂载了./:/app，但容器内用户 UID 不匹配宿主机，造成permission denied—— 解法是在Dockerfile中加USER 1001:1001，并在 compose 中同步指定user: "1001:1001" - 调试端口映射漏配：
EXPOSE 8080只是声明，必须在docker run或 compose 的ports:下显式写"8080:8080"，否则宿主机无法访问
golangci-lint 版本不对 → make lint 失败 → pre-commit 中断 → 提交不了 → 急着跳过钩子 → 后续 CI 报更复杂错误。标准化清单的价值，就在于把这种链式故障点提前暴露、逐个锚定。 
