go modules初始化失败主因是旧依赖管理工具遗留的锁文件与不兼容版本引用，需删锁文件、显式init、replace修复gopkg.in等重定向，并谨慎使用vendor和配置goproxy/gosumdb。
不能“无缝”，但可以快速收敛到稳定状态——关键不是跳过清理，而是精准识别残留干扰源。
go mod init 报 unknown revision 或 cannot determine module path
这是最常见卡点，本质是旧工具（dep/glide）留下的锁文件还在干扰初始化过程，Go Modules 会优先读取 Gopkg.lock 或 glide.lock 中的非法版本（如分支名、提交哈希），然后拒绝解析。
- 先删干净：
rm -f Gopkg.lock glide.lock Godeps.json - 显式指定模块路径：
go mod init github.com/your-org/your-repo，别用.或空参数 - 如果项目里 import 了
gopkg.in/yaml.v2这类重定向路径，初始化后立刻在go.mod里加一行：replace gopkg.in/yaml.v2 => gopkg.in/yaml.v2 v2.4.0 - 执行
go list -m all，若输出里还有大量// indirect条目，说明旧vendor/或缓存里混着未被 import 的包，得人工核对
go build 仍走 GOPATH 或 vendor 目录，新 go.mod 不生效
根本原因是旧 vendor/ 目录没清，或者 GO111MODULE 环境变量被设为 off，导致 Go 退化回老模式。
- 删掉旧
vendor/：rm -rf vendor，别想着复用 - 确认当前环境：
go env GO111MODULE必须是on；go env GOMOD应指向项目根目录下的go.mod - 临时验证是否真走 Modules：
go build -mod=readonly，如果报require xxx: version "v0.0.0-..." used for unknown revision，说明它终于在查go.mod了 - 检查所有
.go文件顶部的 import 路径：旧写法"utils"或"server/handler"必须改成完整路径，比如"github.com/your-org/your-repo/utils"
CI 构建失败：checksum mismatch 或超时
不是网络问题，是 Go Modules 默认启用 GOSUMDB 校验和数据库和 GOPROXY 代理，而旧 CI 脚本没显式配置这两项。
- CI 中必须设置：
GOPROXY=https://proxy.golang.org,direct（或你自己的私有 proxy） - 关闭校验和强制检查（仅限内网可信环境）：
GOSUMDB=off；更稳妥的做法是配私有sum.golang.org镜像 - 删掉脚本里所有
go get安装工具的命令，改用go install golang.org/x/tools/cmd/goimports@latest - Docker 构建时，确保
COPY进去的是带go.mod的代码，且基础镜像 Go 版本 ≥ 1.16（默认开启 Modules）
replace 本地依赖不生效
写 replace 后 go build 还是拉远程包，通常是因为路径或版本格式不对，Go 直接忽略该条目而不报错。
-
replace右侧必须是合法模块路径 + 版本号，例如：replace github.com/foo/bar => ../bar v0.0.0-20230101000000-abcdef123456 - 右侧目录（如
../bar）下必须存在有效的go.mod，且其module声明与左侧一致 - 执行
go mod tidy后，检查go.mod里是否真的出现了这条replace—— 如果没有，说明 Go 认为它无效 - 想验证是否生效：
go list -m -f '{{.Dir}}' github.com/foo/bar，输出应为你的本地路径
迁移真正的复杂点不在命令本身，而在旧项目里那些没被 import 但又被测试或构建脚本间接引用的包——它们不会出现在 go.mod 里，却可能让 go test 或 CI 失败。动手前，先跑一遍 go list -deps ./... 和 grep -r 'import "' . --include="*.go" | grep -v '^.'，比盲目 go mod tidy 更省时间。
