go模块代理配置不生效需检查goproxy是否被覆盖，运行go env goproxy验证当前值；推荐用go env -w goproxy="https://goproxy.cn,direct"全局持久化设置，direct必须置于末尾；私有模块需配合goprivate跳过代理或replace重写路径。
Go模块代理配置不生效？检查 GOPROXY 环境变量是否被覆盖
Go 1.13+ 默认启用模块代理，但很多团队在私有环境或国内网络下需要切换镜像源。最直接的方式是设置 GOPROXY 环境变量，但它容易被 go env -w、shell 启动脚本或 IDE 内置设置覆盖，导致你改了却没生效。
验证当前生效值：运行 go env GOPROXY，输出应类似 https://proxy.golang.org,direct。如果看到空值、off 或只含 direct，说明代理未启用。
- 临时生效：在当前终端执行
export GOPROXY="https://goproxy.cn,direct" - 全局持久化（推荐）：用
go env -w GOPROXY="https://goproxy.cn,direct"，它会写入GOENV指向的配置文件（通常是$HOME/go/env） - 注意顺序：
direct必须放在最后，否则失败后不会回退到直连
想只为某个模块走私有源？用 replace + replace 指向本地或私有仓库
GOPROXY 是全局策略，无法按模块指定源。若只想让 github.com/org/private-lib 走内网 Git 服务器，而其余模块仍走公共代理，就得靠 replace —— 它本质是路径重写，不是源切换。
在项目根目录的 go.mod 中添加：
replace github.com/org/private-lib => git.example.com/org/private-lib v1.2.0
这行表示：所有对 github.com/org/private-lib 的 import，都替换成从 git.example.com 拉取的 v1.2.0 版本。关键点：
- 右侧地址必须是可被
go get解析的 Git URL（支持 SSH、HTTPS），且该仓库需包含标准 Go 模块结构（含go.mod） - 版本号不能省略；若用
=> ./local/path指向本地目录，需确保该目录下有完整go.mod -
replace只影响当前模块构建，不改变依赖模块自身的require声明
公司有统一私有代理服务？配置 GOPRIVATE 跳过代理认证
当你的私有模块域名（如 git.internal.company.com）被 GOPROXY 尝试代理时，会因无权限返回 401 或超时。此时必须告诉 Go：“这些域名不走代理，直连”。方法是设置 GOPRIVATE：
- 值为逗号分隔的域名通配符，例如
GOPRIVATE="git.internal.company.com,*.corp.example.com" - 匹配规则是前缀匹配，
github.com/myorg不会被github.com匹配，必须写全或加* - 如果同时设置了
GOPROXY和GOPRIVATE，Go 会自动对匹配域名跳过代理，直接走git协议或 HTTPS - 务必确认
git命令能正常访问对应地址（比如已配置 SSH key 或 HTTP 凭据）
go mod download 失败提示 “invalid version”？检查模块路径与 tag 格式是否一致
用 replace 或私有代理时常见报错：invalid version: git ls-remote origin refs/heads/v1.2.0 refs/tags/v1.2.0 refs/tags/v1.2.0^{}: exit status 128。根本原因是 Go 要求 tag 名必须严格匹配语义化版本格式（vX.Y.Z），且远程仓库必须存在该 tag。
- 检查远程 Git 仓库：运行
git ls-remote --tags <repo-url></repo-url>，确认输出中有refs/tags/v1.2.0（注意带v前缀） - 如果 tag 是
1.2.0（无v），Go 无法识别，需重打 tag：git tag v1.2.0 <commit></commit>并推送 - 私有代理服务（如 Nexus、JFrog）若缓存了旧的错误 tag 列表，可能需清空缓存或重启服务
模块路径、tag、go.mod 中声明的 module 名三者必须完全一致，差一个字符都会触发校验失败。
