根本原因是Go默认将私有域名导入路径交给公共代理查询，需设置GOPRIVATE让Go直连私有仓库；同时配置Git凭据、确保GOPROXY含direct、禁用GOSUMDB干扰，并避免replace等临时方案。
Go 报“module not found”或“unrecognized import path”，根本不是模块丢了，而是 Go 拒绝走代理去查私有仓库——必须让 GOPRIVATE 明确告诉它“别 proxy，直连”。
go mod tidy 报 git.example.com/xxx@v1.2.0: not found 怎么办
这是最典型的私有仓库识别失败。Go 默认把所有带域名的 import 路径（如 git.example.com/team/lib）都扔给 proxy.golang.org 去查，而私有地址显然不在公共索引里，结果就是 404。
- 确认 Go 版本 ≥ 1.13：
go version，低于这个版本GOPRIVATE不生效 - 设置
GOPRIVATE为你的私有域名（支持通配符）：go env -w GOPRIVATE="git.example.com"或go env -w GOPRIVATE="*.corp.example.com" - 如果子模块路径更深（比如
git.example.com/team/core/v2），建议写成git.example.com/team/*，避免部分工具链漏匹配 - 执行
go env GOPRIVATE验证是否生效，输出应是你填的值
报 unknown revision 或 dial tcp timeout 却能 git clone 成功
说明 Git 层面通了，但 Go 模块系统没用上你的 Git 凭据。它调用 git ls-remote 时可能用了无凭据的 URL（如 https://git.example.com/xxx.git），被拒绝访问。
- 检查 Git 凭据是否配置：运行
git ls-remote https://git.example.com/team/lib.git，看是否要输密码或报 403 - Windows 用户用「凭据管理器」添加 Windows 凭据，类型选「普通凭据」，地址填
https://git.example.com，用户名/PAT 填对 - Linux/macOS 用户运行：
git config --global credential.helper store，然后执行一次git ls-remote触发凭据缓存 - 确保
GOPRIVATE已设，否则 Go 仍会尝试走 proxy，绕过你配好的凭据
go mod download 或 go get 失败但 go build 能过
这说明模块已缓存在本地（$GOPATH/pkg/mod），但 Go 工具链无法从上游解析新版本或校验 checksum，属于“有货但不敢认”的状态。
立即学习“go语言免费学习笔记（深入）”；
- 先清理缓存：
go clean -modcache，再跑go mod tidy - 检查
GOSUMDB是否干扰：私有模块不需要校验，加go env -w GOSUMDB=off（仅调试用，上线建议配GONOSUMDB） - 确认
GOPROXY末尾含direct，例如https://goproxy.cn,direct，否则私有域名请求不会 fallback 到直连 - 别信 IDE 缓存——VS Code 或 GoLand 可能还在读旧的
go.mod状态，重启 Go 扩展或整个编辑器
replace 指令让依赖看起来正常，但实际加载错代码
replace 是临时补丁，不是长期解法。它会让 go build 加载本地路径，但 go list -m all 仍显示原始模块名，CI 或其他协作者拉代码时容易失效。
- 只在调试阶段用：
replace git.example.com/team/lib => ../lib，完事立刻删掉 - 若用于 fork 维护，确保
import路径和replace左侧完全一致（大小写、/v2后缀都不能差） - 检查是否误写了
exclude，它会强制跳过某版本，导致间接依赖断链 - 真正稳定的方案仍是配好
GOPRIVATE+ 凭据 + 直连，让模块系统原生支持私有地址
最容易被忽略的是 GOPROXY 里的 direct 和 GOPRIVATE 的通配粒度——少一个 direct，私有请求就被卡在代理层；多一个 *（比如写成 git.example.com*），就可能匹配失败。这两处写错，其余配置全白搭。
