go mod replace离线失败最常见的原因是用git url而非本地路径，导致离线机无法解析域名；正确做法是用绝对或相对本地路径替换，且目标目录须含匹配module名的go.mod文件。
go mod replace 必须指向本地绝对路径或相对路径
私有模块离线测试失败，最常见的原因是 go mod replace 写了 Git URL（如 git.internal.com/mylib => https://git.internal.com/mylib.git），而离线机根本无法解析域名或建立 TLS 连接。Go 不会把 replace 当作“跳过下载”，而是仍尝试 clone 或 fetch —— 即使你已 go mod vendor 也没用。
正确做法是：在联网机上先 git clone 私有仓库到本地目录（如 ~/repos/mylib），再执行：
go mod edit -replace git.internal.com/mylib=~/repos/mylib
注意：~/repos/mylib 必须包含有效的 go.mod 文件，且版本号（如 v0.1.0）要与 require 行一致；若用相对路径（如 ./mylib），需确保该路径在离线机上存在且位置不变。
- 替换后运行
go mod tidy，确认go.mod中replace行生效，且go list -m all | grep mylib输出应为本地路径而非 URL - 不要混用
replace和vendor/：如果用了replace，go mod vendor不会把被 replace 的模块复制进vendor/，它只 vendor 原始 require 的模块 - CI 或容器构建时，
~/不会被展开，必须用绝对路径（如/home/user/repos/mylib）
离线环境下 go test 会因私有域名解析失败而卡住
go test ./... 在离线机上失败，报错类似 lookup git.internal.com: no such host，往往不是测试代码本身问题，而是 Go 工具链在初始化 module cache 或校验依赖时仍尝试访问原始 import path 的域名。
关键干预点有两个：
- 执行
go env -w GOPROXY=direct—— 不是off或空值，direct才真正禁用代理并跳过所有远程 lookup - 执行
go env -w GOSUMDB=off—— 设为off（不是""），否则 Go 可能 fallback 到默认sum.golang.org - 测试前加
-mod=readonly：运行go test -mod=readonly ./...，防止 Go 尝试自动修正go.mod或拉取缺失依赖
验证是否生效：在离线机上运行 strace -e trace=connect,socket go test -mod=readonly ./... 2>&1 | grep -E "(git\.internal|proxy\.golang|sum\.golang)"，输出应为空。
go list -m all 报错 “no required module provides package” 的真实原因
这个错误常被误判为“依赖没下载”，实际更可能是模块路径不匹配。比如你的测试代码 import "git.internal.com/mylib/util"，但 go.mod 里 require 的是 git.internal.com/mylib v0.1.0，而 replace 指向的本地目录里没有 util 子包（比如漏了 go mod init git.internal.com/mylib 或没提交 util/ 目录）。
排查步骤：
- 检查本地 replace 目录下是否有对应 import 路径的子目录（
ls ~/repos/mylib/util） - 进入该目录，运行
go list -m，输出应为git.internal.com/mylib，不是mylib或空 - 确认该目录下
go.mod第一行是module git.internal.com/mylib，与 import 路径严格一致 - 若子包路径含二级域名（如
git.internal.com/team/mylib），replace 必须完整匹配，不能只写git.internal.com
vendor/ + replace 组合使用时 go build -mod=vendor 仍失败
你以为 go mod vendor 后加 -mod=vendor 就万事大吉，但若项目含 replace，Go 构建时仍会尝试从原始路径解析模块 —— 尤其当测试文件（*_test.go）里 import 了 replace 模块的子包，而 vendor 目录里又没它时。
根本解法不是绕开 replace，而是让 vendor 包含它：
- 在联网机上，先
go mod edit -replace git.internal.com/mylib=./mylib（用相对路径，方便打包） - 然后
go mod vendor—— 此时 vendor 目录下会出现vendor/git.internal.com/mylib/，内容来自./mylib，不是原始 Git 仓库 - 把整个项目（含
vendor/）拷到离线机，**不要**再设replace，因为 vendor 已覆盖 - 离线构建用
go build -mod=vendor，不再依赖任何外部路径
注意：go mod vendor 不处理 //go:embed 或 cgo 的头文件，这些仍需单独同步。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
