私有模块路径必须以域名或完整URL开头，如git.example.com/team/utils；升级需更新go.mod中require版本号或用go get命令；replace仅用于开发调试，上线前必须删除；回滚应使用go get指定旧版本。
私有模块路径必须带域名或完整 URL 前缀
Go 模块系统默认只信任以域名（如 git.example.com）或完整 URL（如 https://git.example.com/team/repo）开头的模块路径。如果直接用相对路径或纯目录名（如 mylib 或 ./mylib），go mod tidy 会报错：no required module provides package。
正确做法是统一使用类似 git.example.com/team/utils 的路径定义模块，即使它托管在内网 GitLab 或自建 Gitea 上。Go 不验证域名是否真实可访问，只靠该格式触发代理/替换逻辑。
- 初始化时在私有包根目录运行：
go mod init git.example.com/team/utils
- 引用时也必须用相同路径：
import "git.example.com/team/utils" - 若域名不可解析，需配合
GOINSECURE或GOPRIVATE环境变量跳过 TLS 校验
升级私有模块要改 go.mod 中的 require 行，不是改本地文件
很多人误以为修改本地私有包代码后运行 go mod tidy 就能“升级”，其实不会——Go 只根据 go.mod 中 require 指定的版本拉取，不感知本地文件变更（除非显式 replace）。
升级本质是更新依赖声明中的版本号，并让 Go 工具链重新解析和下载对应 commit/tag。
立即学习“go语言免费学习笔记（深入）”；
- 手动编辑主项目
go.mod，把git.example.com/team/utils v0.1.2改成v0.2.0 - 或用命令行更新：
go get git.example.com/team/utils@v0.2.0
- 确保私有仓库已打 tag：
git tag v0.2.0 && git push origin v0.2.0 - 若未打 tag，可用 commit hash：
go get git.example.com/team/utils@abcd123
replace 是开发期临时绑定，上线前必须删掉
开发调试私有模块时常用 replace 指向本地路径，例如：
replace git.example.com/team/utils => ./local-utils
这会让所有 import "git.example.com/team/utils" 实际加载 ./local-utils 下的代码。但它仅作用于当前模块，且 go build 时不会校验 ./local-utils/go.mod 是否匹配原模块路径——极易导致构建失败或行为不一致。
-
replace不参与版本解析，go list -m all显示的仍是原始版本号 - CI/CD 流水线中若未清理
replace，会因路径不存在而失败 - 上线前务必删除
replace行，并用go get拉正式版本 - 临时调试可用
-mod=readonly防止意外写入：go build -mod=readonly
回滚依赖靠 go get 指定旧版本，不是删 go.sum
遇到新版本引入 bug，想快速回退？别删 go.sum 或 go.mod 手动改——这容易破坏校验和或引发间接依赖冲突。
最安全的方式是明确指定上一个已知稳定版本，让 Go 自动重算整个依赖图。
- 执行：
go get git.example.com/team/utils@v0.1.2
- 检查结果：
go list -m git.example.com/team/utils应返回v0.1.2 -
go.sum会自动补全旧版本的校验和；若缺失，go mod download可强制获取 - 若回滚后编译失败，大概率是其他依赖仍要求更高版本，此时需用
go mod graph | grep查间接引用链
私有模块没有语义化版本约束力，tag 命名随意会导致 go list -m -u 无法识别更新。建议强制使用 vX.Y.Z 格式打 tag，并在 CI 中校验。
