replace路径必须相对于当前go.mod所在目录，用Unix斜杠、以../开头、目标含匹配module名的go.mod；错误会导致cannot find module等报错。
replace 指令里写相对路径为什么总报错
因为 go.mod 中的 replace 路径是相对于当前 go.mod 文件所在目录计算的，不是相对于 replace 行本身，也不是相对于项目根目录——很多人误以为写 ./local-module 就行，结果 Go 工具链在解析时根本找不到那个路径。
常见错误现象：go build 或 go mod tidy 报错 cannot find module providing package xxx: working directory is not part of a module，或者提示 replaced module must be in a version control repository（其实是路径没解析成功，Go 误判为远程模块）。
- 必须用 Unix 风格斜杠（
/），即使在 Windows 上也要写../local-module，不能写..\local-module - 路径不能以
./开头（Go 会拒绝解析），但可以以../开头 - 目标目录下必须有有效的
go.mod文件，且模块名（module声明）要和被替换的原始模块名完全一致
正确的 replace 写法和验证步骤
假设你主项目在 /home/user/myapp，本地模块在 /home/user/local-utils，而 myapp/go.mod 依赖的是 github.com/myorg/utils，你想用本地 local-utils 替换它。
操作顺序比语法更重要：
立即学习“go语言免费学习笔记（深入）”；
- 先确保
local-utils/go.mod第一行是module github.com/myorg/utils（必须和原依赖名一致） - 在
myapp/go.mod的require下方添加：replace github.com/myorg/utils => ../local-utils
- 运行
go mod tidy—— 如果没报错，说明路径可解析、模块名匹配、且local-utils本身能被正常go list - 再执行
go build，观察是否真的加载了本地代码（比如改一行fmt.Println("local")看输出）
replace 后 go run 仍然用旧代码？检查 GOPATH 和缓存
replace 生效的前提是 Go 工具链能“看到”你的本地模块，但它可能被缓存或环境干扰。
典型表现：改了本地模块代码，go run 却没反应，还是跑老逻辑。
- 执行
go clean -modcache清掉模块缓存（尤其当你反复增删replace时） - 确认没意外设置
GOPATH，且当前目录下没有残留的vendor/目录（它会绕过replace） - 用
go list -m all | grep utils查看实际加载的模块路径，输出应类似：github.com/myorg/utils v0.0.0-00010101000000-000000000000 => ../local-utils - 如果输出里没出现
=>符号，说明replace根本没生效，回头检查路径拼写和模块名一致性
多层嵌套项目中 replace 的路径怎么算
路径始终从当前 go.mod 所在目录出发，一级级向上/向下找。比如主项目在 project/api，本地模块在 project/lib，那 project/api/go.mod 里的写法就是：
replace github.com/myorg/lib => ../lib
容易踩的坑：
- 不要试图用
../../跳出 GOPATH 或模块根目录之外——Go 不允许指向非模块目录 - 如果本地模块本身也依赖其他模块，它的
go.mod必须自洽；否则tidy会失败，而不是静默忽略 - CI 环境里慎用相对路径
replace，最好改用git@或file://绝对路径（但后者跨机器不可移植）
相对路径 replace 是开发期的临时方案，真正提交前得确认本地模块已发布到仓库，否则协作者拉代码就直接卡死。
