go modules初始化需显式指定合法module path，如go mod init github.com/username/repo；私有仓库依赖需配置go mod edit -replace与git url替换；go.sum变动应通过go mod tidy解决；v2+版本升级必须修改import路径和module path。
Go Modules 初始化失败：go mod init 报错或生成错误 module path
常见现象是执行 go mod init 后，模块名变成 cmd 或本地路径（如 /home/user/project），导致后续 go build 找不到依赖或无法发布。根本原因是没传入合法的 module path，Go 会退化为猜测路径。
正确做法是显式指定一个符合语义的、可解析的路径，通常对应未来代码托管地址：
- 本地开发阶段可用占位符，如
go mod init example.com/myapp（无需真实存在） - 若项目将托管在 github，直接用
go mod init github.com/username/repo - 避免使用相对路径、中文、空格或下划线开头；module path 区分大小写，但建议全小写
初始化后检查 go.mod 文件第一行是否为 module github.com/xxx/yyy —— 这是后续所有依赖解析的根。
go get 拉取私有仓库依赖时提示 “unknown revision” 或 “no matching versions”
这是 Go Modules 默认只信任 https 公共源，对私有 Git 服务（如自建 gitlab、ssh 地址）缺乏配置所致。不是网络问题，而是 Go 不知道如何解析和认证该源。
立即学习“go语言免费学习笔记（深入）”；
解决需两步配合：
- 告诉 Go 如何替换模块源：
go mod edit -replace=private.org/lib=git@private.org:group/lib.git - 配置 Git 协议行为（关键）：
git config --global url."ssh://git@private.org/".insteadOf "https://private.org/" - 若用 SSH，确保
~/.ssh/config中已配好对应 Host 别名和密钥
注意：go get 默认拉取 latest commit，不带 tag；如需特定版本，应先在私有仓库打 tag（如 v1.2.0），再运行 go get private.org/lib@v1.2.0。
go.sum 文件频繁变动，CI 构建失败或提示 “checksum mismatch”
go.sum 记录每个依赖模块的校验和，用于防篡改。变动常见于：同一模块不同人本地拉取了不同 commit（尤其未打 tag 的分支）、代理缓存污染、或模块作者重写了历史 tag。
稳定构建的关键操作：
- 禁止手动修改
go.sum；出问题优先用go mod tidy -v重新生成 - CI 中务必执行
go mod download再构建，确保所有依赖从 GOPROXY 下载而非本地缓存 - 若团队用公司 proxy，确认其支持
sum.golang.org校验服务，或配置GOSUMDB=off（仅限内网可信环境）
真正危险的是 “checksum mismatch” 错误——它意味着你本地下载的 zip 内容与 go.sum 记录不符，必须查清来源，不能简单删掉 go.sum 重来。
升级 major 版本依赖（如 v1 → v2）后编译报 “cannot find package”
Go Modules 要求 major 版本 ≥ v2 必须体现在 module path 中，例如 github.com/sirupsen/logrus 的 v2 版本实际 module path 是 github.com/sirupsen/logrus/v2。否则 Go 会当成两个无关模块处理。
升级步骤不能只靠 go get -u：
- 先看目标库文档是否声明了 v2+ 的 module path（常在 README 或 go.dev 页面顶部）
- 用
go get github.com/xxx/yyy/v2@latest显式拉取带 /v2 后缀的路径 - 更新代码中所有
import "github.com/xxx/yyy"为import "github.com/xxx/yyy/v2" - 运行
go mod tidy清理旧引用；旧 v1 版本不会自动删除，需手动确认无残留
很多开发者卡在这里，是因为盲目相信 go get -u 会自动处理路径变更 —— 它不会，module path 是硬编码在代码里的。