发布私有 Go 模块时，最常被忽略的一点是 go 命令并不会因为你把仓库设为私有就自动切换认证方式。它的默认拉取链路仍然会优先访问公共代理 proxy.golang.org，并向公共校验服务提交模块哈希。因此需要先从模块路径和仓库地址的映射开始配置。
模块路径与仓库映射
Go 模块的拉取入口是模块路径，而不是一个单独的下载地址。模块路径通常需要映射到一个可被 Git 访问的仓库地址，例如 github.com/company/private-module 表示 GitHub 上的私有仓库。go get 首次解析这个路径时，会访问公共代理或直接访问 VCS 服务。私有仓库不对外公开，公共代理自然无法读取，最终会返回 404 或认证错误。
要让 go 命令绕开公共代理，必须配置 GOPRIVATE。它支持 Go 的路径匹配规则，逗号分隔多个前缀。建议按组织前缀配置，而不是为每个仓库单独设置，例如：
go env -w GOPRIVATE=github.com/company/* go env -w GONOPROXY=github.com/company/* go env -w GONOSUMDB=github.com/company/*
在这组配置里，GONOPROXY 控制哪些路径不走公共代理，GONOSUMDB 控制哪些路径不写入公共校验数据库。Go 1.13 之后，设置 GOPRIVATE 会同时给这两项设置默认值，但显式写清楚可以避免旧版本工具链或者公司内部镜像策略造成干扰。配置完成后，可以执行 go env 检查是否真正生效。
绕开代理只解决了第一个问题。接下来 go 会直接调用 Git 拉取代码，因此仓库必须对当前机器可见。最稳妥的方式是使用 SSH 协议，并通过 Git 的 insteadOf 把 HTTPS 地址改写成 SSH 地址，这样不用在模块路径里写特殊协议。
git config --global url."git@github.com:".insteadOf "https://github.com/"
如果是自建 GitLab，后缀可能类似 git.mycorp.com，同样按前缀改写：
git config --global url."git@git.mycorp.com:".insteadOf "https://git.mycorp.com/"
版本标签与主版本号如何配合
私有仓库内部的版本发布同样遵守语义化版本规则。正式版本不能只依赖某个提交哈希，而必须创建带 v 前缀的标签。比如提交代码后执行：
git add . git commit -m "feat: init private module" git tag v1.0.0 git push origin v1.0.0
go get 在拉取模块时会根据标签解析版本。如果仓库没有标签，go 会生成类似 v0.0.0-时间戳-提交哈希 的伪版本。这种伪版本在开发阶段勉强能用，但它不稳定，难以进行依赖追踪，也不适合发布给团队使用。每次合并代码都应该先在合并分支上打标签，再让 CI 触发发布，避免标签和线上提交内容不一致。
当模块出现不兼容变更，需要从 v1 升级到 v2 或更高主版本时，必须同步修改模块路径。Go 的规则是主版本大于 1 时，模块路径要带上 /v2、/v3 这样的后缀。例如 v2 模块的 go.mod 开头应为：
module github.com/company/private-module/v2 go 1.22
同一个仓库兼容多个主版本时，通常采用子目录方式。根目录继续维护 v1，新建 v2 目录并在其中初始化新的 go.mod，所有 import 路径改成 github.com/company/private-module/v2/包名。发布时在仓库根目录打 v2.0.0 标签。这样老版本依赖不会被打断，新版本也能被正确解析。如果只修改标签但未修改模块路径，go get 会提示版本与路径不匹配，私有仓库的这个错误往往比公共模块更难排查，因为代理缓存不会给出完整上下文。
本机免密拉取与 CI 配置
本机开发时，SSH 免密是最简单的方案。配置好 SSH key 后，可以用 ssh -T git@github.com 验证。如果上一步已经设置了 insteadOf，那么 go get 内部调用 Git 时会自动使用 SSH URL，不再弹出用户名密码输入。对于 GitHub 来说，模块路径仍然是 github.com/company/private-module，go.mod 里不需要写成 SSH 前缀。
CI 环境不能交互，因此需要提前注入认证信息。常见做法有两种。第一种是把只读部署密钥写入 CI 变量，并在流水线里启动 SSH agent。第二种是在构建镜像里写入 .netrc 文件，供 HTTPS 认证使用：
machine gitlab.com login oauth2 password glpat-xxxxxxxx
同时建议在 CI 中设置 GIT_TERMINAL_PROMPT=0，避免凭据缺失时卡住等待输入。对于需要深度拉取标签的情况，还要确保 CI 的 Git 配置不是 shallow clone，否则可能找不到版本标签。GitHub Actions 可以设置 fetch-depth: 0，GitLab CI 可调整 GIT_DEPTH。
如果私有模块依赖了其他私有模块，GOPRIVATE 必须覆盖所有相关前缀，只配置最终模块地址是不够的。比如依赖链条涉及 github.com/company/base-lib 和 github.com/company/toolkit，最省力的方式是直接配置 github.com/company/*。团队规模较大时，可以把这些配置写入基础镜像或全局初始化脚本，避免每个新成员重复猜错。
常见报错与排查清单
私有模块拉取失败时，第一步不要直接怀疑网络。先按顺序确认：go env GOPRIVATE 是否覆盖了模块路径；git ls-remote 本机能否访问仓库；go clean -modcache 后重试是否仍报同样错误。很多问题来自旧缓存或者环境变量只在当前 shell 生效。
常见错误包括 invalid version: unknown revision、reading https://...: 404 Not Found、missing go.sum entry for module 以及 terminal prompts disabled。第一个通常说明标签未推送或 CI 没有拉取到标签，第二个说明仍走了公共代理，第三个说明 sumdb 校验未关闭。第四个则是认证配置缺失，需要检查 SSH key、insteadOf 或 .netrc。
还有一个容易误判的情况：公司使用内部代理，但私有模块路径依然匹配到公共代理。此时可以临时把 GOPROXY 设置为 direct 进行排查，确认是否代理规则导致。若直连没问题而代理报错，就需要调整内部代理的排除规则。定位完成后再恢复统一代理配置，保证公共模块仍可走缓存。
Go私有模块Golang私有仓库版本控制修改时间：2026-09-17 18:18:48