replace指令是Go模块本地联调唯一可靠方式，必须满足三条件：左侧路径与被替换模块go.mod中module声明完全一致；右侧为含匹配module名的go.mod目录；执行go mod tidy校验生效。
replace 指令怎么写才生效
本地联调 Go 模块依赖，replace 是唯一可靠且官方支持的方式。它不是“复制代码”，而是编译时路径重定向，必须满足三个硬性条件才能生效：
-
replace左侧的模块路径（如github.com/user/utils）必须与被替换模块的go.mod中module声明**完全一致**，包括大小写和斜杠方向； - 右侧路径（如
../go-utils）必须是**含有效go.mod文件的目录**，且该文件里module行也得匹配左侧； - 执行
go mod tidy后，Go 会校验路径合法性并更新go.sum—— 如果报invalid version或no matching versions，大概率是右侧目录没go.mod或模块名不一致。
相对路径 vs 绝对路径选哪个
一律用**相对路径**。绝对路径（如 /home/you/dev/go-utils）在团队协作或 CI 环境中必然失败，因为路径不存在或权限不对。相对路径基于 go.mod 所在目录计算，可移植性强：
- 假设主项目在
~/proj/api，本地依赖在~/proj/utils，则replace github.com/user/utils => ../utils； - 路径中不能包含
~或环境变量（如$HOME），Go 不解析它们； - 如果依赖目录不在同级，可用多级
../，但避免跨出项目根目录（否则go mod tidy可能拒绝加载）。
为什么改了本地包代码却没生效
常见原因不是 Go 缓存，而是 import 路径没同步更新：
- 确认代码里 import 的路径仍是原始远程路径（如
"github.com/user/utils"），不是本地路径 ——replace不改变 import 语句； - 检查是否误删了
go.mod中的replace行，或执行过go mod tidy -v导致自动清理（它会移除未被 import 的 replace）； - 运行
go list -m all | grep utils，输出应含=>符号和本地路径；若只显示版本号，说明 replace 未生效； - 修改本地包后，必须重新
go run或go build，Go 不会自动热重载依赖包。
CI/CD 构建前必须处理 replace
replace 是纯开发期手段，上线构建时必须移除，否则会因路径不存在而失败：
立即学习“go语言免费学习笔记（深入）”；
- 不要提交带
replace的go.mod到主干分支； - 撤销单个替换：运行
go mod edit -dropreplace=github.com/user/utils； - 批量清理：
go mod edit -dropreplace=all（慎用，确保所有本地依赖已发布）； - 如果必须保留调试能力，可用
//go:build !production+ 构建 tag 隔离，但需配套 CI 脚本判断环境变量来跳过 replace。
最易被忽略的一点：本地模块即使没打 tag，Go 也会生成伪版本（如 v0.0.0-20260804152210-abc1234def56），这个版本号在 go.sum 中固定，但一旦你提交了新 commit，伪版本就变 —— 所以联调期间别动 go.sum，也别让别人 go mod tidy 覆盖它。
