Go模块路径必须与代码托管地址严格一致，否则go get失败；私有模块需配置GOPRIVATE和git url重写；版本号须符合语义化规范且带v前缀，主版本≥2时路径须含/vN后缀。
模块路径必须与代码托管地址一致
Go 模块路径（module 声明）不是随意起的别名，它直接决定 go get 时的导入解析行为。如果你把模块路径设为 github.com/yourname/myproject，但实际代码托管在 gitlab.com/yourname/myproject，其他用户执行 go get github.com/yourname/myproject 就会失败——Go 工具链会按路径前缀去对应域名找 Git 仓库，不会自动跳转。
常见错误包括：
- 本地开发时用
module myproject（无域名），后续迁移到 GitHub 后不改go.mod，导致依赖无法被正确拉取 - 公司内网使用私有 GitLab，却设成
github.com/org/proj，go mod tidy报错unknown revision - 路径中混用大小写（如
MyProject），而 Git 服务器对大小写敏感或不敏感，引发跨平台导入不一致
私有模块需配置 GOPRIVATE 和 git config
当模块路径形如 gitlab.company.com/internal/utils，Go 默认当作公共模块走 HTTPS 或 GOPROXY，结果 403 或超时。必须显式告诉 Go：“这个路径不走代理，直接走 Git”。
两个必要动作缺一不可：
立即学习“go语言免费学习笔记（深入）”；
- 设置环境变量：
GOPRIVATE=gitlab.company.com/internal/*（支持通配符，但不能写成*全局关闭） - 配置 Git 认证方式：
git config --global url."ssh://git@gitlab.company.com/".insteadOf "https://gitlab.company.com/"，否则go get仍尝试 HTTPS 并卡在登录 - 若用 SSH 私钥，确保
~/.ssh/config中 Host 别名与模块路径中的主机名完全匹配（例如Host gitlab.company.com，不能漏掉.com）
版本号必须符合语义化规范且带 v 前缀
Go 的模块版本识别严格依赖格式：v1.2.3、v0.1.0、v2.0.0+incompatible 都合法；1.2.3、v1.2、release-1.2.3 全部无效，go mod tidy 会忽略或报错 invalid version。
特别注意：
- 主版本号 ≥2 时，路径必须包含
/v2后缀，例如模块路径是example.com/lib，v2 版本发布后应改为example.com/lib/v2，否则 Go 不认为它是独立大版本 -
go tag必须带v：git tag v1.0.0✅，git tag 1.0.0❌ - 本地调试用
replace时，目标路径也得是有效模块路径，不能写相对路径或../local-copy
多模块项目慎用 replace 和 exclude
大型项目拆分成多个 go.mod 时，容易用 replace 强制指向本地目录来绕过发布流程。这在单机开发没问题，但会导致 CI 构建失败、同事 go mod download 失败、或者 go list -m all 输出混乱。
更稳妥的做法：
- 只在
main模块的go.mod中用replace，且仅限开发阶段；上线前删掉，改用真实版本号 - 避免在库模块（非 main）中写
replace，它会被下游继承，污染整个依赖图 -
exclude是临时止血手段，不是长期方案；一旦排除了某个版本，所有间接依赖它的模块都会失去该版本上下文，可能触发意外降级
模块路径本身不难设，难的是让路径、Git 仓库、版本标签、网络策略四者咬合严丝合缝。任何一环松动，go build 可能还成功，但 go test -mod=readonly 或 CI 环境里就会暴露问题。
