私有模块版本管理需满足四点：一、用v前缀语义化标签（如v1.0.0）而非分支；二、配置goPRIVATE跳过代理与校验；三、确保git协议可访问且认证可靠；四、模块路径须与仓库地址严格匹配。
Go 项目使用私有模块时，版本控制的核心在于：让 go mod 能正确解析、拉取和锁定私有仓库的特定版本（如 v1.2.3 或 v0.5.0-alpha），同时避免因权限、网络或路径问题导致构建失败。关键不是“能不能用私有模块”，而是“如何让 Go 工具链像对待 github.com 那样信任并管理你的私有模块版本”。
私有模块必须走语义化版本标签
Go 的模块版本解析严格依赖 Git 标签（如 v1.0.0、v2.1.5）。私有仓库不能只靠分支（如 main 或 dev）做版本标识——go get 和 go mod tidy 默认不识别分支作为版本，除非显式加 @branch（不推荐用于生产）。
- 所有发布版本必须打带
v前缀的轻量标签：git tag v1.0.0，然后git push origin v1.0.0 - 主版本升级需同步更新模块路径（如从
git.example.com/mylib升级到git.example.com/mylib/v2），否则 Go 不认为是新版本 - 预发布版本可用
v1.0.0-beta.1，Go 支持标准语义化版本比较逻辑
配置 GOPRIVATE 绕过代理与校验
默认情况下，go 命令会尝试通过 proxy.golang.org 拉取模块，并对 checksum 进行公共校验。私有模块既不在代理中，也不在 sum.golang.org 上注册，必须显式声明“这些域名下的模块是私有的”。
- 执行：
go env -w GOPRIVATE=git.example.com,git.internal.company - 支持通配符：
GOPRIVATE=*.example.com（注意：不支持**或正则） - 设置后，
go将直连 Git 服务器（走 ssh 或 https），跳过代理和校验，但要求本地 Git 能正常 clone 对应仓库
确保 Git 协议可访问且认证可靠
私有模块的拉取本质是 git clone。如果 go get 失败，90% 是 Git 访问环节出问题，而非 Go 本身。
- 推荐统一使用 SSH 协议（如
git@example.com:team/lib.git），并在~/.ssh/config中配置 Host 别名和 IdentityFile - 若用 HTTPS，需配置 Git 凭据助手（
git config --global credential.helper store）或使用git config --global url."https://Token@github.com".insteadOf "https://github.com"类方式注入 token - 验证方法：
git ls-remote git@example.com:team/lib.git refs/tags/v1.0.0能返回结果，go mod download git.example.com/team/lib@v1.0.0才可能成功
模块路径与仓库地址要严格匹配
Go 要求 go.mod 中的 module 名（如 git.example.com/team/lib）必须能被解析为真实可访问的 Git 仓库地址。不匹配会导致 go mod tidy 报错 “unknown revision” 或 “no matching versions”。
- 模块路径就是 import 路径，也是 go 命令拼接 Git URL 的依据（例如
git.example.com/team/lib→https://git.example.com/team/lib.git） - 如果仓库实际地址是
https://git.example.com/teams/go-lib，那 module 名就必须写成git.example.com/teams/go-lib，不能简写 - 可通过
go env -w GONOSUMDB=git.example.com确保该域名下模块跳过 checksum 数据库校验（配合 GOPRIVATE 使用更稳妥）
基本上就这些。不需要额外服务（如 Athens）、不依赖 GOPROXY 中转，纯靠 Go 原生命令 + Git 配置 + 语义化标签，就能稳定管理私有模块版本。难点常在权限和路径一致性，而不是 Go 本身。