Go从1.11引入模块系统后，依赖管理变得前所未有的方便，但这份便利建立在一个前提上：模块托管在公共仓库中，能够被proxy.golang.org和sum.golang.org正常访问。一旦你的公司代码放在GitLab私有仓库或者自建的Gitea服务上，直接go get就会报错，常见的是404、410或者校验和不匹配。这篇文章就来聊聊如何让私有模块也能被正常拉取、正常控制版本。
为什么私有模块需要单独处理
要理解私有模块的问题，得先知道Go命令拉取依赖的完整链路。默认情况下，go get会先访问公共模块代理proxy.golang.org，代理负责下载模块并生成缓存；下载完成后还会去sum.golang.org查询校验和，确保模块内容没有被篡改。这套机制对公共模块非常安全，但对私有模块就是灾难——公共代理根本没有权限访问你的私有仓库，它只能返回404或者错误信息。
所以私有模块的核心思路就一句话：告诉Go命令，这些路径前缀的模块不要走公共代理，也不要走公共校验库，直接从源仓库拉取。这需要理解三个关键环境变量的分工。GOPRIVATE是一组通配符模式，匹配到的模块会同时设置GONOSUMDB和GONOPROXY的效果，也就是既不走代理也不校验。后两个变量可以单独精细控制，比如你希望私有模块走公司内部代理但不做公共校验，就单独设置GONOSUMDB。
GOPRIVATE配置与认证方式
配置GOPRIVATE非常简单，比如公司仓库域名是git.mycompany.com，执行下面这条命令即可：
go env -w GOPRIVATE=git.mycompany.com/* # 多个仓库域名的写法，用逗号分隔 go env -w GOPRIVATE=git.mycompany.com,github.com/my-org/*
注意通配符的语义：git.mycompany.com只匹配这个域名本身，git.mycompany.com/*才匹配它下面的所有路径。团队内部一般直接对整个域或者整个组织路径加通配符，省得每加一个仓库就改一次配置。这条命令会写入GOENV环境文件（通常在用户目录的config/go/env），对所有项目生效。
绕过代理之后，Go命令会退回到直接的版本控制协议去拉取模块，这时候认证就成了关键。对HTTPS方式的仓库，Go会读取.netrc文件中的凭据。在Linux和macOS上是~/.netrc，Windows上可以放在%USERPROFILE%\_netrc，内容格式如下：
machine git.mycompany.com login your-name oauth 或 password 替换成访问令牌
这里强烈建议使用访问令牌而不是账号密码，GitLab可以在个人设置里生成Personal Access Token，权限只勾选read_api和read_repository即可，泄露后的影响范围可控。如果你更习惯SSH方式，可以在Git的全局配置里把这个域名的URL强制改写成SSH地址：
git config --global url."git@git.mycompany.com:".insteadOf "https://git.mycompany.com/"
这样即使go.mod里记录的是HTTPS地址，实际拉取时也会走SSH密钥，避免在每个环境里维护netrc文件。
私有模块的版本策略与tag管理
绕过代理只是解决了能不能拉到的问题，版本控制还得靠规范的tag管理。Go模块的版本解析完全依赖仓库tag，一个符合规范的发布流程应该是：功能开发在feature分支进行，合并到主干后打上形如v1.4.2的tag，go get时就能精确拉取这个版本。这里有几个容易踩的坑值得展开说说。
第一个坑是不打tag就引用。没有tag时Go会用伪版本（pseudo version），形如v0.0.0-20240115093000-abcdef123456，中间是提交的UTC时间，后面是commit哈希前12位。伪版本能用但很脆弱：它是不可变的，一旦上游force push，本地缓存的伪版本和远端就对不上了；而且伪版本完全不能表达语义化版本的意图，消费方没法判断这次升级是否包含破坏性变更。正式依赖私有模块时，请务必给仓库打tag。
第二个坑是破坏性变更的处理。按照语义化导入规则，v2及以上版本必须在模块路径末尾追加主版本号后缀，比如：
module git.mycompany.com/platform/user-service/v2
同时在消费方的go.mod里，import语句也要带上v2后缀。很多团队偷懒不改模块路径，直接打v2.0.0的tag，结果go get根本拉不到新版本。如果确实不想加后缀，还有一个折中办法是用+v2.0.0这种incompatible标记，但这只适用于模块还没迁移到Go modules的时代产物，新项目不要这么做。
常见报错排查与进阶方案
配置完成后如果仍然报错，可以按链路逐段排查。go get git.mycompany.com/xxx: module not found通常是GOPRIVATE通配符没匹配上，用go env GOPRIVATE确认配置；401或要求输入密码说明认证失败，检查netrc的machine字段是否和仓库域名完全一致，一个字符都不能差；verifying module: checksum mismatch则说明模块之前从公共校验库拿到过校验和，需要清理本地缓存中的相关记录，删除go.sum里对应行或执行go clean -modcache后重试。
团队规模扩大后，更推荐搭建内部模块代理。开源的Athens可以直接部署一套私有代理，全局设置GOPRIVATE之外再配GOPROXY=https://athens.mycompany.com,https://proxy.golang.org,direct，私有模块由Athens统一缓存和分发，公共模块依然享受代理加速。这样CI环境不需要每台机器都配置SSH私钥，只需要能访问内部代理即可，安全性和构建速度都有保障。配合CI中固定版本号的go.mod和go.sum一起提交入库，整套私有模块的版本控制体系就完整了。