go mod tidy 必须在含 go.mod 的模块根目录执行，否则报错或无效；多模块项目需分别进入各子模块目录运行；其行为受 go.mod 中声明的 go 版本约束，且默认不扫描条件编译或测试文件，需配合 -v 或 -tags 参数确保完整性。
go mod tidy 必须在 module 根目录下执行
很多人在子目录里运行 go mod tidy，结果依赖没更新、go.sum 不变、甚至报 no modules found。这是因为 go mod 工具只认当前路径向上最近的 go.mod 文件——它不会自动跳转或递归查找。
- 确保每次执行前都在项目根目录（即含
go.mod的目录），可用ls go.mod验证 - CI 脚本中建议显式
cd $(git rev-parse --show-toplevel)再运行go mod tidy - 如果项目含多个 module（如
/cmd/api和/cmd/cli各有go.mod），需分别进入对应目录执行，不能“一键 tidy 全局”
go.mod 中的 go version 声明影响 tidy 行为
go mod tidy 会根据 go.mod 首行的 go 1.21（或类似）版本号，过滤掉不兼容的依赖版本。比如某依赖只支持 go 1.22+，而你的 go.mod 写的是 go 1.20，go mod tidy 就可能降级到旧版、甚至失败退出。
- 团队必须统一
go.mod第一行的 Go 版本，且该版本需与asdf .tool-versions和 CI 镜像一致 - 不要依赖
GOVERSION环境变量或本地go version输出——go mod tidy只看go.mod文件 - 升级 Go 版本时，先改
go.mod，再go mod tidy，否则可能锁住旧版依赖
避免手动编辑 go.sum，但要定期校验它是否被篡改
go.sum 是由 Go 工具链自动生成和维护的校验文件，手动删行、加行、改 checksum 都会导致后续 go build 或 go test 失败，报错类似 checksum mismatch。
- 提交前检查：
go mod verify应返回空（无输出）；若有异常，说明本地缓存或远程模块已被污染 - CI 中建议加一步：
go mod download && go mod verify，防止因代理缓存脏数据导致构建不一致 - 若需重置校验，不要删
go.sum，而是运行go mod tidy -v（带详细日志），它会自动重建并校验
pre-commit hook 中运行 tidy 容易漏掉测试文件里的 import
很多团队在 pre-commit 里加 go mod tidy，却发现 PR 提交后 CI 还是报依赖缺失——因为 go mod tidy 默认只扫描 *.go 文件，而测试文件（如 xxx_test.go）里的 import 若未被主逻辑引用，就容易被忽略。
- 确保
_test.go文件也参与分析：pre-commit 脚本中用go mod tidy -v，观察日志是否包含xxx_test.go - 更稳妥的做法：在 hook 中先
go list ./...，确认所有包（含 test）都能被解析，再跑go mod tidy - 如果项目用了
//go:build integration等条件编译标记，需额外传-tags=integration给go mod tidy，否则对应 import 会被跳过
go.mod 执行了 go mod tidy。三者只要一个错位，依赖状态就不可复现。
