“no matching versions”错误根本原因常是模块路径、版本标签或语义化版本规则不匹配，如私有仓库未配GOPRIVATE、tag命名不合规（如v1.2缺补零）、模块路径含非法字符等。
go mod download 报错“no matching versions”怎么定位
根本不是网络或镜像问题，而是模块路径、版本标签或语义化版本规则不匹配。常见于私有仓库未配置 GOPRIVATE、tag 命名不合规（如 v1.2 缺少补零）、或模块路径含非法字符。
- 先运行
go list -m -versions github.com/user/repo看远程到底有哪些可识别版本；若报错invalid version，说明 tag 不符合vX.Y.Z格式 - 检查
go env GOPRIVATE是否包含该域名；没配会导致 go 默认走 proxy，而私有地址返回 404 或重定向失败 - 用
curl -I https://proxy.golang.org/github.com/user/repo/@v/list模拟 proxy 请求，确认是否真返回空或 404 - 临时绕过 proxy 测试：
GO_PROXY=direct go mod download，成功则证明是 proxy 配置或鉴权问题
go mod download 卡住或超时怎么办
不是单纯等更久，而是模块解析卡在某一层间接依赖的校验或重定向上。尤其当 go.sum 中存在多个校验和但对应不同 commit，go mod download 会尝试逐个验证。
- 加
-x参数看实际执行命令：go mod download -x，输出里会暴露卡在哪条gitfetch 或curl请求 - 检查
go env GOSUMDB；设为off可跳过校验（仅调试用），避免因 sumdb 不可达导致阻塞 - 若卡在某个私有模块，确认
git config --get-all credential.helper是否已配置凭据，否则 ssh/git+https 请求会 hang 住 - 避免混用
replace和go mod download：replace 指向本地路径时，download 会忽略它，但若路径不存在或权限不对，反而触发 fallback 到远程下载逻辑
go mod download 后 go build 仍报 “cannot find module”
下载成功 ≠ 构建可用。本质是 go.mod 中的 require 声明与实际下载内容不一致，或模块路径被 replace 覆盖后未生效。
- 运行
go list -m all | grep target-module，确认目标模块是否出现在输出中；没出现说明require行缺失或版本写错 - 检查
replace是否拼写错误：比如replace github.com/a/b => ./local，但./local目录下没有go.mod，go 会静默忽略该 replace - 执行
go mod verify；若失败，说明go.sum记录的校验和与当前下载内容不匹配，需删掉go.sum后重新go mod tidy - 注意
go mod download不修改go.mod或go.sum，它只缓存到$GOPATH/pkg/mod；真正同步状态靠go mod tidy
CI 中 go mod download 失败但本地正常
几乎全是环境变量或路径差异导致，不是代码问题。最常踩的坑是 GO111MODULE 和 GOPROXY 在 CI 中未显式设置。
立即学习“go语言免费学习笔记（深入）”；
- CI 脚本开头必须加：
export GO111MODULE=on和export GOPROXY=https://proxy.golang.org,direct；不能依赖默认值，尤其旧版 Go 或 Docker 镜像可能默认auto且无go.mod - 检查 CI 工作目录是否为模块根目录；
go mod download必须在含go.mod的目录下执行，否则报go: no modules found - 私有模块场景下，CI 机器需预装 git 凭据或配置
~/.netrc；ssh-agent或git credential在容器中通常未初始化 - 避免在 CI 中使用
replace指向相对路径（如../sibling）；CI 构建是 clean checkout，兄弟目录根本不存在
no matching versions 实际是 tag 名写成 v1.2 而不是 v1.2.0，或者 cannot find module 其实是 replace 指向的本地目录漏了 go.mod 文件。 
