go工具链要求replace右侧必须用./或../开头的相对路径，绝对路径和~会被静默忽略；本地模块go.mod的module名须与replace左侧完全一致；go mod tidy会自动删除不合法的replace行。
replace 右侧必须用 ./ 开头的相对路径
Go 工具链只接受以 ./ 开头的相对路径作为 replace 的右侧值，绝对路径（如 /home/user/lib）或用户主目录缩写（如 ~/lib）会被静默忽略——不是报错，而是直接跳过该行，继续用远端版本。
相对路径基准点是 go.mod 所在目录，不是你当前执行 go build 的工作目录。比如项目结构是：
myapp/
├── go.mod
└── main.go
libs/
└── mylib/
├── go.mod
└── utils.go
那么在 myapp/go.mod 里要写：replace github.com/user/mylib => ../libs/mylib，不能写成 ./libs/mylib（那会去 myapp/libs/mylib 找）。
-
../libs/mylib合法，且推荐：路径清晰、团队协作时无需改写 -
./local/mylib合法，但要求local/mylib目录真实存在且位于myapp/下 -
../mylib合法，只要上层目录里真有那个文件夹 -
mylib或../mylib/（末尾斜杠）非法：前者不是相对路径，后者路径格式不被识别
本地模块的 go.mod module 名必须完全匹配左侧
replace 能生效的前提，是右侧本地路径下存在有效的 go.mod 文件，且它的第一行 module 声明必须和左侧一模一样——包括大小写、路径层级、是否带版本后缀（如 v1.2.3）。
例如你在 go.mod 写了：replace github.com/User/Utils => ../utils，那 ../utils/go.mod 的第一行必须是：module github.com/User/Utils，而不是 github.com/user/utils 或 github.com/User/Utils/v2。
- 大小写错一个字母，
go list -m all会显示原远程模块，不显示=>替换标记 - 本地
go.mod为空或只有module行但没运行过go mod tidy，可能被跳过 - 如果本地模块用了
replace自己依赖，它不会自动传导到主模块；主模块仍需显式require对应版本
go mod tidy 会校验并可能删掉非法 replace
执行 go mod tidy 时，Go 会检查每条 replace 是否满足所有条件：路径可访问、本地有 go.mod、module 名匹配、无循环引用。任一失败，该行就会被自动从 go.mod 中移除——不会警告，也不会提示哪条错了。
所以如果你发现刚加的 replace 没了，大概率是 go mod tidy 把它当无效配置清理了。
- 先确认本地路径下能
go list -m出正确 module 名 - 再确保主模块
require块里已声明该模块（哪怕只是旧版本），否则tidy可能认为“这模块根本不需要”，连带删掉replace - CI 环境慎用相对路径：建议用
file:///absolute/path或通过GOEXPERIMENT=aliases go mod edit -replace动态注入
replace 不传播，下游模块看不到你的本地替换
replace 是单模块作用域的，只影响当前 go.mod 所在项目的构建行为。如果你的项目被别人 require 为依赖，对方的构建过程完全不会感知你写的 replace，也不会继承过去。
这意味着：调试时你本地能跑通，不代表下游集成时也能用同一套本地路径。想让协作方也用本地版，得让他们各自在自己的 go.mod 里加相同 replace，或者改用 go work 管理多模块工作区。
- 别指望靠
replace统一团队开发环境——它不跨模块生效 - 发布前务必手动删掉或注释掉所有
replace行，否则go build在干净环境里会失败 - 真正需要共享本地修改的场景，优先考虑
go work use ./moduleA ./moduleB，比一堆replace更可控
go.mod 文件必须存在且内容合法，而且 replace 行必须严格落在 require 块之后——这两处出错，Go 都不报错，只沉默跳过。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
