如何在Golang中模拟模块发布测试 Go语言本地模块替换实战

replace语句必须写在go.mod文件的replace段中，且位于require块之后、exclude或retract之前；写错位置或误入go.sum会导致失效。

replace 语句写在哪？为什么 go.mod 里不生效

本地模块替换必须写在 go.mod 文件的 replace 段，且只能出现在 require 块之后、exclude 或 retract 之前。常见错误是把 replace 写在 require 上面，或误塞进 go.sum —— 那里只存校验和，写进去会被 go mod tidy 清掉。

• replace 必须指向一个含有效 go.mod 的目录（可以是相对路径，如 ./mylib，也可以是绝对路径）
• 被替换的模块名（左边）必须与 require 中声明的完全一致，包括版本号（如 github.com/user/lib v1.2.0），哪怕你只想替换 v1.2.0 这个版本
• 如果目标模块还没打 tag，别用 latest 或 master —— Go 不认这些，得用 => ./local-path 显式映射

go build 时 replace 不起作用？检查 GOPROXY 和 vendor 状态

即使 go.mod 写对了，go build 仍可能拉远端模块：因为 GOPROXY 默认开启，且 vendor 目录存在时会优先用它。这不是 bug，是 Go 的确定性依赖策略。

• 运行 go env GOPROXY，如果输出不是 off 或包含 direct，就可能绕过 replace —— 临时关掉： GOPROXY=off go build
• 如果有 vendor/ 目录，go build -mod=readonly 会拒绝读取 replace；要么删掉 vendor，要么加 -mod=mod 强制走 module 模式
• 执行 go mod graph | grep your-module-name，能直接看到当前解析出的实际依赖路径，比猜靠谱得多

测试时 import 路径没变，但实际加载的是本地代码？验证方法

替换成功后，import 路径不变（仍是 "github.com/user/lib"），但源码来自本地。光看编译不报错不够，得确认 runtime 行为真变了。

• 在本地模块里加一行 fmt.Println("loaded from local")，然后运行主程序 —— 输出出现才算真正生效
• 用 go list -m -f '{{.Dir}}' github.com/user/lib 查看 Go 实际使用的模块根目录，结果应该是你的本地路径，而不是 $GOPATH/pkg/mod/...
• 如果模块有 init 函数或包级变量，改个值再构建，观察行为是否同步更新 —— 这比看日志更直接

发布前忘记清理 replace？CI 构建失败的典型原因

replace 是开发期临时手段，进 CI 或发布包时必须移除，否则别人 clone 你的代码根本跑不起来：他们的机器上没有你本地那个路径。

• CI 脚本里加一句 grep -q "replace" go.mod && echo "Error: replace found in go.mod" && exit 1，提前拦截
• 不要用 go mod edit -replace 动态加 replace 后直接提交 —— 容易漏删；推荐用分支隔离：开发分支留 replace，合并到 main 前手动删
• 如果必须保留某种“可切换”能力，改用 //go:build local + 单独的 main_local.go 文件控制导入，而不是靠 replace 欺骗模块系统

replace 的边界很窄：它只影响当前 module 的构建视图，不改变 import 路径，也不传播给下游。这点一旦混淆，调试成本会陡增。