Go Modules初始化失败主因是模块路径未显式指定，应使用go mod init github.com/user/project；需清理vendor、校验replace路径及CI环境GOPROXY与Go版本。
Go Modules 初始化失败：go mod init 报错 “cannot determine module path”
旧项目没用 go.mod，直接运行 go mod init 却报这个错，本质是 Go 不知道该给模块起什么名字。它会尝试从当前路径、go.work、环境变量甚至 Git remote 推断，但多数老项目路径不规范或没配 Git，就卡住。
- 最稳妥的做法是显式指定模块路径：
go mod init github.com/yourname/yourproject（哪怕暂时不打算开源，路径也得合法） - 别用本地绝对路径（如
/home/user/myproj）或相对路径（./myproj），Go 模块路径必须是可解析的域名格式 - 如果项目已推送到 GitHub，且本地
git remote get-url origin能返回正确地址，go mod init会自动取用——但别依赖这个，先确认 Git 配置干净 - 执行后检查生成的
go.mod文件第一行：module github.com/xxx/yyy，确保它和你未来import时写的前缀一致，否则其他包 import 会找不到
vendor 目录残留导致 go build 仍走旧依赖路径
旧项目习惯用 go vendor 或手动维护 vendor/，升级 Modules 后若不清除，go build 默认仍优先读 vendor/，等于白迁——尤其当你改了 go.mod 里的版本却没生效，八成是这问题。
- 执行
go mod vendor前先删掉原有vendor/目录：rm -rf vendor - 确认
GO111MODULE=on（Go 1.16+ 默认开启，但旧 shell 可能残留off或auto） - 临时禁用 vendor 测试是否真走 Modules：
go build -mod=readonly，如果报错说缺某个 module，说明它终于在查go.mod了 - 想彻底弃用 vendor？删掉目录后，在
go.mod里加// +build !vendor没用；真正有效的是别再运行go mod vendor，也不提交vendor/到 Git
replace 指令写错：本地调试依赖时路径不生效
开发中常要临时替换某个依赖为本地修改版，用 replace 是标准做法，但新手容易写成相对路径或漏掉版本号，导致 go build 依旧拉远端包。
- 正确写法：
replace github.com/some/lib => ../some-lib（注意：右边是文件系统路径，不是模块路径；且必须是绝对路径或相对于go.mod所在目录的相对路径） - 如果
../some-lib下没有go.mod，Go 会报no required module provides package—— 此时要么进该目录运行go mod init github.com/some/lib，要么用replace github.com/some/lib => ./local-fork并确保local-fork/go.mod存在 -
replace只影响当前模块，子模块不会继承；若依赖链深层还有引用，可能需要多层 replace 或统一升级上游 - 上线前务必删掉
replace行，否则 CI 构建会失败——建议加注释如// DEV ONLY: replace ...，方便搜索清理
CI 环境构建失败：GOPROXY 或 Go 版本不匹配
本地能跑，CI 上 go build 却提示找不到模块或 checksum 不匹配，大概率是环境差异。Modules 对 Go 版本和代理策略更敏感，旧 CI 镜像常忽略这点。
立即学习“go语言免费学习笔记（深入）”；
- 检查 CI 使用的 Go 版本：Go 1.11–1.15 需设
GO111MODULE=on；1.16+ 默认开启，但某些 Alpine 镜像打包时可能关掉了 - 确认
GOPROXY设置合理：export GOPROXY=https://proxy.golang.org,direct是通用安全值；若公司有私有 proxy，必须显式配置，不能依赖默认 - checksum 错误（
verifying github.com/xxx@v1.2.3: checksum mismatch）通常因go.sum未提交或被修改——确保go.sum和go.mod一起 git commit - 如果用 Docker 构建，基础镜像别用
golang:alpine（缺少 ca-certificates，连 proxy 都通不了），改用golang:slim或完整版
迁移真正的麻烦不在命令本身，而在所有隐式依赖突然变成显式声明——比如某个工具链脚本悄悄 import 了内部 utils，但没出现在老项目的 import 列表里，Modules 一开就暴露。动手前，先 go list -f '{{.ImportPath}}' ./... 过一遍真实依赖树。
