replace指向本地路径在CI/CD中必然失败，因CI环境无对应本地路径，导致go build报“找不到模块”；提交前必须删除replace或改用fork commit哈希替代，且需确保GOPRIVATE、import路径与本地go.mod完全匹配。
replace 指向本地路径在 CI/CD 中必然失败
CI 环境里没有你本机的 ../some-pkg，go build 会直接报错：找不到模块。这不是权限或网络问题，是路径根本不存在。很多团队在本地用 replace github.com/foo/bar => ../bar 调试得很顺，一推到 GitHub Actions 或 Jenkins 就卡住。
真正可行的做法只有两种：
- 调试阶段用
replace，但提交前必须删掉对应行，再跑一次go mod tidy - 改用
replace github.com/foo/bar => github.com/your-fork/bar v0.0.0-20260801120000-abc123（指向 fork 的 commit），这样本地和 CI 都能拉到同一份代码 - 如果必须本地开发+远程构建，建议把调试分支单独维护，主干
go.mod始终不带本地路径replace
go mod tidy 不会自动清理失效的 replace
go mod tidy 只负责补全缺失依赖、校验 go.sum、同步 require 列表，它不会检查你写的 replace 是否还有效。比如你删了本地目录 ../bar，但 go.mod 里还留着那行 replace，go build 会立刻失败，而 go mod tidy 完全沉默。
所以每次切换环境前要手动确认：
立即学习“go语言免费学习笔记（深入）”；
- 执行
go list -m github.com/foo/bar，看输出是否为本地路径（如果是，说明replace生效） - 检查
go.mod里有没有残留的replace行，尤其是调试完忘记删的 - CI 流水线开头加一行
grep -q "=> \.\." go.mod && echo "ERROR: local replace detected" && exit 1，防误提交
私有模块 + replace + GOPRIVATE 必须三者对齐
如果你用 replace 指向公司内网 GitLab 上的私有模块，但没配 GOPRIVATE，go get 会尝试走代理（如 https://proxy.golang.org），然后 404；即使配了 GOPRIVATE，若 replace 写成 gitlab.example.com/group/lib => ./lib，而实际 import 是 "gitlab.example.com/group/lib/v2"，版本后缀不匹配也会导致包找不到。
关键检查点：
-
go env GOPRIVATE必须包含模块域名，例如gitlab.example.com -
replace左侧的模块路径，必须和代码里import的路径完全一致（包括/v2这类主版本后缀） - 本地路径替换时，确保该路径下有合法的
go.mod文件，且module声明与 import 路径匹配
线上发布前必须验证 replace 是否已撤出
最容易被忽略的一点：replace 是“当前模块专用”的，它不会传递给下游。也就是说，你发一个库 A，A 的 go.mod 里写了 replace github.com/x/y => ./local-y，别人 go get A 时，github.com/x/y 依然按原始版本解析——你的本地替换对使用者完全无效，反而可能让你测试通过、别人集成失败。
发布前务必：
- 运行
go list -m all | grep github.com/x/y，确认输出是远程 tag 或 commit，不是(devel)或本地路径 - 临时新建空目录，
go mod init test，go get your-module@latest，看能否 clean 构建 - 如果项目含
vendor，记得go mod vendor后再检查vendor/下的对应模块是否来自预期源
replace 是调试利器，但它的生命周期必须严格限定在“你自己的机器上、你正在改的那一小段时间里”。一旦跨出这个边界，它就从工具变成隐患。 
