go.sum不是锁版本文件，而是依赖完整性校验文件，记录各模块zip包及go.mod的SHA256哈希值，构建时自动比对，不一致则报checksum mismatch并中断；必须提交至Git，不可手动编辑，唯一合法更新方式是go mod tidy等命令触发自动写入。
Go环境能跑起来、go test 能执行、模块依赖不报错——这三件事只要有一件卡住，就不是“一看就通”，而是卡在了官方文档没说清的路径细节上。
go version 有输出，但 go mod init 报错 “cannot find module root”
这不是 Go 没装好，而是你当前目录不在一个“干净”的项目根路径下。Go Modules 要求项目根目录不能是 $GOPATH 的子目录（旧习惯容易踩坑），也不能嵌套在另一个已有 go.mod 的父目录里。
- 用
pwd看当前路径，确保它是个全新空目录，比如/tmp/myapp或$HOME/dev/myapp - 别在
$HOME/go/src下初始化——那是 GOPATH 时代的老路，现在会触发兼容模式警告甚至失败 - 如果父目录有
go.mod（比如你在公司 monorepo 里 cd 进某个子目录），go mod init会拒绝覆盖，此时加-modfile参数或换到独立路径再试
go test 找不到测试函数，或提示 “no buildable Go source files”
Go 测试文件必须满足两个硬性条件：文件名以 _test.go 结尾，且包名和被测代码**完全一致**（不是 package main 就写 package main）。
- 检查文件名是否拼错，比如
utils_test.go写成utils.test.go或utils_test.g0 - 确认测试文件和被测文件在同一个目录下；Go 不支持跨目录自动关联（不像 pytest 那样靠命名约定扫描）
- 如果被测函数是 unexported（小写开头），测试函数也必须在同一包内才能访问——别试图在
package testutil里测package main的私有函数
用 go test -v 跑通了，但 CI 上 go test ./... 报依赖缺失
本地能过是因为你手动 go get 过某些包，但 go.mod 没记录；CI 是干净环境，只认 go.mod 里声明的依赖。
立即学习“go语言免费学习笔记（深入）”；
- 运行
go mod tidy强制同步：它会删掉未使用的依赖，同时补全所有实际 import 的包 - 别依赖
go run或go build时的隐式下载——它们不会更新go.mod，只有go mod tidy或显式go get xxx@version才会写入 - 如果项目用了
replace本地调试，CI 构建前记得注释掉，否则构建机找不到你本机路径
VS Code 里能断点调试，但终端 go test 里日志不输出
这是 t.Log 和 t.Logf 的默认行为：只有测试失败或加了 -v 参数才打印。很多人误以为“没输出 = 没执行”，其实是静默了。
- 临时加
-v查看完整日志：go test -v -run TestDB_Connect - 别在测试里用
fmt.Println——它绕过测试框架，CI 日志里可能被截断或乱序 - 如果要强制输出（比如查并发竞态），用
t.Log("debug: ", x)+go test -v，而不是改 stdout
最常被忽略的一点：Go Modules 的 go.sum 不是可选文件。它校验依赖完整性，删掉它会导致 go test 在首次运行时重新下载并生成新哈希——CI 可能因此超时或拉取非预期版本。别把它加进 .gitignore，除非你明确知道后果。
