私有模块托管不必须开启goproxy=direct，关键在于模块路径匹配、https可达、go-get响应正确及tag不可变；错误配置会导致解析失败或checksum mismatch。
私有模块托管必须开启 GOPROXY=direct 吗？
不是必须，但默认行为下不设代理会导致 go get 尝试走公共代理（如 proxy.golang.org），直接失败或跳转 404。私有模块要被正确解析，关键不是关不关代理，而是让 Go 工具链能「定位到模块根路径」并「信任该路径的响应」。
常见错误现象：go get example.com/my/internal@v1.0.0: unrecognized import path "example.com/my/internal": https fetch: Get "https://example.com/my/internal?go-get=1": dial tcp: lookup example.com: no such host —— 这说明 DNS 或 HTTPS 服务未就绪，而非代理问题。
- 若私有域名已配置 DNS 且服务器支持 HTTPS（推荐），保留
GOPROXY=https://proxy.golang.org,direct即可，Go 会自动 fallback 到 direct - 若用 HTTP（如内网
http://gitlab.internal/my/lib），必须设GOPROXY=direct并配GOINSECURE=gitlab.internal - 若用自签名证书，还需加
GOTRUST=1（Go 1.21+）或系统级信任证书
如何让 go.mod 正确识别私有模块路径？
模块路径（module 声明）必须与你最终访问它的 URL 完全一致，包括协议、端口、大小写。比如你在 git clone https://gitlab.internal:8443/my/lib.git 克隆代码，那么 go.mod 第一行必须是：module gitlab.internal:8443/my/lib —— 缺少端口或协议都会导致解析失败。
常见错误：把模块路径写成 my/lib 或 github.com/my/lib，结果 go get 去公网找，或者返回 invalid version: unknown revision。
立即学习“go语言免费学习笔记（深入）”；
- 路径中不能含
git://、ssh://等非 HTTP(S) 前缀；Go 只认 URL 风格路径 - 若用子路径模块（如
gitlab.internal/my/lib/sub），需确保该路径下有独立go.mod，且其module行与导入路径严格匹配 - Git 标签名必须符合语义化版本格式（如
v1.2.0），否则go list -m -versions查不到
私有 Git 服务器如何响应 go-get 请求？
Go 客户端在解析模块时，会向 https://example.com/my/lib?go-get=1 发 GET 请求，期望返回含 <meta name="go-import"> 的 HTML 页面。这不是可选功能，是协议强制要求。
如果你用的是标准 Git 服务（如 GitLab/GitHub 自托管版），默认不提供该响应，必须手动补上。最简方案是在 Web 服务器（Nginx/Apache）里加路由规则：
<meta name="go-import" content="example.com/my/lib git https://git.example.com/my/lib.git">
注意 content 三段式：模块路径、vcs 类型（git）、仓库地址（必须可被 git clone 直接使用）。
- GitLab CE/EE 从 v15.1 起支持原生
?go-get=1响应，但需开启go_imports_enabled配置项 - 若用 Gitea，需启用
[other] ENABLE_GO_GET = true并确保反代透传 query 参数 - 避免用重定向代替 meta 标签：Go 不跟随 302，只解析 HTML body 中的
<meta>
客户端拉取私有模块时为何提示 checksum mismatch？
这是 Go 模块校验机制触发的典型报错：verifying example.com/my/lib@v1.0.0: checksum mismatch。根本原因不是网络问题，而是 go.sum 记录的哈希值与当前下载内容不一致 —— 多数情况是你改过 tag 内容但没更新 tag（Git 允许 force-push tag，但 Go 不允许覆盖已有版本哈希）。
解决思路不是删 go.sum，而是让版本可追溯：
- 永远不要
git push --force已发布的 tag；应删旧 tag、打新 tag（如v1.0.0-1），再go mod tidy - 若只是本地调试，可用
replace绕过校验：replace example.com/my/lib => ./local/path - 私有仓库若未启用 Go module proxy 缓存，每次
go get都重新 fetch，容易因网络抖动导致临时校验失败；建议部署athens或goproxy.cn私有实例
模块路径拼写、HTTPS 可达性、meta 标签格式、tag 不可变性——这四点漏掉任一，都可能让 go get 在看似成功后突然卡在 checksum 阶段。
