go modules 初始化失败主因是旧依赖管理工具遗留的锁文件与不兼容版本引用，需删锁文件、显式init、replace修复gopkg.in等重定向，并谨慎使用vendor和配置goproxy/gosumdb。
Go Modules 初始化失败：go mod init 报错“unknown revision”
常见于项目原本用 dep 或 glide 管理依赖，go.mod 为空或缺失，执行 go mod init 后立即报错，比如：unknown revision v1.2.3 或 module declares its path as: github.com/xxx/yyy but was required as: gopkg.in/xxx/yyy.v1。
根本原因是旧工具留下的 Gopkg.lock 或 glide.lock 中记录了不兼容的版本引用（如分支名、提交哈希、非语义化 tag），而 Go Modules 默认只认符合 vX.Y.Z 格式的 tag，且要求模块路径与代码中 import 路径严格一致。
- 先删掉旧锁文件：
rm -f Gopkg.lock glide.lock，避免go mod tidy自动读取干扰 - 运行
go mod init时显式指定模块路径，别依赖猜测：go mod init github.com/your-org/your-repo - 如果项目里用了
gopkg.in这类重定向 import，需手动在go.mod中用replace修复，例如：replace gopkg.in/yaml.v2 => gopkg.in/yaml.v2 v2.4.0 - 执行
go mod tidy前，建议先go list -m all看是否已有残留的间接依赖——有就说明旧vendor/或缓存还在影响判断
vendor 目录要不要保留？go mod vendor 的副作用
很多团队迁移时下意识执行 go mod vendor，以为能“无缝替代旧 vendor”，结果 CI 构建变慢、本地 go run 行为异常，甚至测试失败。
Go Modules 默认走 GOPROXY + 缓存机制，vendor/ 不再是构建必需项；强行启用反而绕过校验、隐藏版本漂移问题，且 go mod vendor 不处理 //go:embed 或 cgo 所需的文件。
立即学习“go语言免费学习笔记（深入）”；
- 除非 CI 环境明确禁止外网访问（且你已配置好私有 proxy 和 checksum db），否则不要生成
vendor/ - 若必须保留，记得在
.gitignore中加一行/vendor，并确保所有成员禁用GO111MODULE=off -
go mod vendor后，go build默认仍走 module 模式；要强制用 vendor，得加-mod=vendor参数，漏写就会行为不一致 - 检查
vendor/modules.txt是否包含大量// indirect条目——这是旧依赖残留信号，应配合go mod graph | grep定位未被直接 import 的模块
CI/CD 流水线卡在 go get -u：GOPROXY 和 GOSUMDB 必须显式配置
本地跑通了，CI 却频繁失败：要么 go get -u 超时，要么报 checksum mismatch。这不是网络问题，是 Go Modules 在验证阶段默认启用了校验和数据库（GOSUMDB）和代理（GOPROXY），而旧流水线脚本没适配。
尤其当项目依赖私有 GitLab 或 GitHub Enterprise 时，GOSUMDB 无法验证其 commit，GOPROXY 也无法转发请求，必须主动关闭或替换。
- CI 启动时第一行就该设：
export GOPROXY=https://proxy.golang.org,direct（国内可换为https://goproxy.cn） - 私有仓库场景下，
GOSUMDB=off是最简方案；更安全的做法是自建 sumdb 或用GOSUMDB=sum.golang.org+https://sum.golang.org配合 allowlist - 避免在脚本里混用
go get和go mod tidy：前者会升级依赖，后者才做最小收敛；CI 应统一用go mod tidy -v+go build - 确认 CI 使用的 Go 版本 ≥ 1.16（默认开启 modules），低于此版本必须加
GO111MODULE=on
从 Dep 迁移后 test 失败：replace 和 exclude 的误用
测试里出现 cannot load github.com/some/pkg: cannot find module providing package，或者某个包的 mock 行为异常——大概率是 go.mod 里写了 replace 或 exclude，但没覆盖全部 import 路径。
Dep 的 [[override]] 是全局生效的，而 Go Modules 的 replace 只作用于模块路径字面匹配，大小写、子路径、vendor 内引用都可能逃逸。
-
replace的左边必须和go list -m all输出的模块路径完全一致（包括vX.Y.Z后缀） - 如果想屏蔽某个间接依赖，
exclude比replace更干净，但仅对主模块有效；被其他依赖作为 direct 引入的，仍会拉取 - 测试时用
go test -mod=readonly可快速暴露哪些测试代码偷偷触发了隐式go get - 用
go mod graph | grep 'some/pkg'查清它被谁引入，再决定是replace、exclude，还是直接升级上游依赖
模块路径拼写错误、replace 覆盖不全、GOSUMDB 校验拦截——这三个点只要漏查一个，迁移后的构建就可能在某次 PR 后突然崩掉，而且不容易复现。
