Go私有包管理需满足三点：模块路径必须含域名（如git.internal/myorg/mylib）；开发用replace指向本地模块，上线前须删除；多项目共享需配置GOPROXY（如Athens）和GOPRIVATE（如git.internal）跳过公共代理。
Go 没有中心化私有包管理服务（如 npm private registry），但可通过 go mod + 本地或远程代码托管 + 正确的 replace / proxy 配置实现稳定私有包管理。关键不在“搭系统”，而在“让 go build 和 go get 正确解析和拉取私有路径”。
私有模块路径必须带域名（即使本地）
Go 要求模块路径（module 声明）是类似 URL 的格式，否则 go mod tidy 会报错：malformed module path "mylib": missing dot in first path element。这不是约定，是强制语法要求。
即使包只在内网用，也要用假域名（如 git.internal/myorg/mylib）或真实内网域名（如 git.company.local/myteam/utils）。不支持纯路径如 mylib 或 ./mylib。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 初始化私有模块时，用
go mod init git.internal/myorg/mylib（域名可任意，但需全局一致） - 所有引用该包的地方，import 路径也必须完全匹配：例如
import "git.internal/myorg/mylib" - 如果用 GitLab/GitHub 私有仓库，路径应与 clone URL 主机名对齐，比如
gitlab.example.com/group/project
go.mod 中用 replace 临时指向本地路径（开发阶段）
开发中频繁改私有包又不想每次 go mod vendor 或推送到远端，replace 是最直接的方式。它绕过网络拉取，强制将某个模块路径映射到本地文件系统路径。
示例：主项目 go.mod 中添加：
replace git.internal/myorg/mylib => ./internal/mylib
注意点：
-
./internal/mylib必须是合法 Go 模块（含go.mod文件），且其module声明必须为git.internal/myorg/mylib -
replace只影响当前模块构建，不传递给下游依赖；其他项目想用你的私有包，仍需自己配置replace或走 proxy - 上线前务必删掉
replace行，否则 CI 构建会失败（因为 CI 环境没有那个本地路径）
公司级复用需配 GOPROXY + 私有代理服务（如 Athens）
当多个团队/项目要共享同一套私有包，且希望 go get 自动拉取、缓存、校验，就得部署 Go module proxy。Athens 是目前最成熟的开源方案，支持 Git、FS、S3 后端。
配置要点：
- 启动 Athens 服务后，设置环境变量：
GOPROXY=http://athens.company.local（同时设GOSUMDB=off或配私有 sumdb） - Athens 需提前允许私有域名：启动参数加
--download-mode=unrestricted或配置allowed列表 - 确保私有 Git 仓库支持 HTTPS Basic Auth 或 SSH Agent 转发（Athens 拉取时需能认证）
- 客户端无需改
go.mod，只要import路径匹配（如git.internal/myorg/mylib），go get就会自动经 proxy 解析并缓存
常见失败原因：GOPRIVATE 环境变量漏设
这是最常被忽略的一环。只要 GOPROXY 不为 direct，Go 默认会对所有模块走 proxy；但私有路径（如 git.internal/*）不能暴露给公共 proxy（如 proxy.golang.org），否则会 404 或泄露代码。
必须显式告诉 Go 哪些路径“跳过 proxy，直连”：
export GOPRIVATE="git.internal,git.company.local"
多个域名用逗号分隔，支持通配符 *（如 git.internal/*），但不支持正则。
漏设后果：
-
go get git.internal/myorg/mylib报错：module git.internal/myorg/mylib: reading http://proxy.golang.org/git.internal/myorg/mylib/@v/list: 404 Not Found - 即使你本地跑着 Athens，Go 仍会先尝试公共 proxy，直到超时才 fallback —— 这个过程慢且不可控
-
GOPRIVATE必须在所有开发者机器、CI 环境、Docker 构建镜像中统一配置，缺一不可
私有包管理真正的复杂点不在部署 Athens，而在于路径命名、GOPRIVATE 范围划定、以及 replace 与 proxy 场景的切换时机——这些地方一旦不一致，就会出现本地能编、CI 编不过、同事拉不下来等典型问题。
