正确配置私有仓库依赖需先设置GOPRIVATE跳过代理和校验，再通过SSH密钥或PAT配置Git认证，必要时在go.mod中使用replace指令映射路径，并在CI/CD中注入凭证和配置环境变量，确保构建机可访问私有库。
在使用 Golang 开发项目时，经常会遇到需要引入私有仓库依赖的情况，比如公司内部的公共库托管在私有 Git 服务器（GitHub、GitLab、Gitea 等）。由于这些仓库无法被公开访问，Go 模块默认的下载机制会失败。本文将介绍如何正确配置和管理 Golang 中的私有仓库依赖，确保项目可以顺利构建。
配置 GOPRIVATE 跳过代理和校验
Go 在模块模式下默认会通过 proxy.golang.org 下载模块，并验证其校验和。对于私有仓库，我们不希望这些请求被转发到公共代理，也不应上传校验信息到 checksum 数据库。
解决方法是设置 GOPRIVATE 环境变量，告诉 Go 哪些仓库是私有的，应跳过代理和校验：
go env -w GOPRIVATE=git.company.com,github.com/your-org/private-repo你也可以使用通配符：
立即学习“go语言免费学习笔记（深入）”；
go env -w GOPRIVATE=*.company.com,github.com/your-team/*这个设置后，所有匹配的模块路径将不会经过公共代理，也不会上传 checksum 到 sum.golang.org。
配置 Git 凭据访问私有仓库
Go 下载模块依赖实际上是通过 Git 克隆代码，因此必须确保本地 Git 能够认证并拉取私有仓库。
常见方式包括：
- SSH 密钥认证：将 SSH 公钥添加到 GitHub/GitLab 等平台，本地保留对应的私钥（通常在 ~/.ssh/id_rsa 或 ~/.ssh/id_ed25519）
- HTTPS + Personal Access Token (PAT)：适用于不能用 SSH 的环境，将 token 当作密码使用
例如，使用 SSH 方式，你的模块导入路径应为：
import "git.company.com/team/project"确保该路径对应的是可通过 SSH 克隆的地址，如：git@git.company.com:team/project.git
如果使用 HTTPS，可配置 Git 凭据存储：
git config --global credential.helper store
之后第一次克隆时输入用户名和 PAT，Git 会记住凭证。
使用 replace 替换模块路径（可选）
有时私有仓库的导入路径与实际 Git 地址不一致，或你想临时指向本地开发版本，可以在 go.mod 中使用 replace 指令：
replace github.com/your-org/private-lib => git@github.com:your-org/private-lib.git v1.2.3或者指向本地路径进行调试：
replace github.com/your-org/private-lib => /Users/you/gocode/private-lib注意：replace 只影响当前项目的构建，不应提交用于生产环境的 replace 到主分支，除非目标是固定依赖版本。
CI/CD 中的私有仓库配置
在 CI 环境中（如 GitHub Actions、GitLab CI），需要确保构建机器也能访问私有依赖。
常见做法：
- 在 CI 中注入 SSH 私钥，并配置 known_hosts 防止首次克隆确认提示
- 设置 GOPRIVATE 环境变量
- 提前运行 git config 设置 SSH URL 替换（如把 https 换成 ssh）
示例 GitHub Actions 片段：
- name: Set up Gouses: actions/setup-go@v4
with:
go-version: '1.21'
- name: Configure Git
run: |
git config --global url."git@github.com:".insteadOf "https://github.com/"
echo "GOPRIVATE=github.com/your-org/*" >> $GITHUB_ENV
然后将部署密钥或个人访问令牌配置为 GitHub Secret，并在步骤中写入 SSH 密钥文件。
基本上就这些。只要确保 GOPRIVATE 设置正确、Git 认证可用，Go 就能正常拉取私有依赖。整个过程不复杂，但容易忽略细节导致下载失败。建议团队统一规范模块路径和认证方式，减少协作成本。
