replace 必须位于 go.mod 文件末尾 require 块之后、独立成行，右侧为以 ./ 开头且指向含匹配 module 名的 go.mod 的本地根目录，否则 go mod tidy 会静默忽略或删除该行。
replace 本地相对路径必须写对位置、格式和模块名，否则 Go 工具链会静默忽略——不是没生效，是根本没匹配上。
replace 语句必须放在 go.mod 文件末尾的 require 块之后
Go 不允许把 replace 写在 require 块内部，也不接受嵌套或前置。常见错误是把它塞进 require ( ... ) 括号里，或者放在 module 行之前。
-
replace必须独立成行，位于所有require语句之后、exclude或retract之前（如果有的话） - 位置错会导致
go mod tidy直接删掉该行，且不报错 - 验证方式：运行
go mod tidy后打开go.mod，确认replace行还在原位、未被清除
右侧路径必须是以 ./ 开头的相对路径，且指向模块根目录
replace 右侧不是任意子目录，而是整个模块的根——即包含有效 go.mod 文件的目录。路径计算基准是 go.mod 所在目录，不是你当前 shell 的工作目录。
- 正确写法：
replace github.com/user/lib => ./local/lib（./local/lib/go.mod存在且第一行为module github.com/user/lib） - 错误写法：
replace github.com/user/lib => /home/you/lib（绝对路径虽能用，但破坏协作一致性） - 错误写法：
replace github.com/user/lib => ./local/lib/src（指向子目录，go无法识别为模块） - 错误写法：
replace github.com/user/lib => ../lib（看似合理，但若go.mod在子目录下，相对路径就失效）
本地模块的 go.mod 中 module 名必须与 replace 左侧完全一致
Go 对模块路径大小写、斜杠、版本后缀都敏感。哪怕只差一个字母或一个 v，replace 就不会触发。
- 检查本地模块的
go.mod第一行：module github.com/user/lib—— 必须和replace左侧一模一样 - 如果远程依赖写的是
github.com/user/lib v1.2.3，replace左侧不能省略版本，但实际仍只匹配路径部分；Go 会忽略版本号做路径匹配 - 本地模块不能只有空
go.mod：至少要执行过go mod init github.com/user/lib，且最好有require或导出符号，否则某些 Go 版本可能跳过验证 - 常见现象：
go list -m all | grep lib显示的仍是远程版本，说明左侧路径没对上，不是网络问题
go mod tidy 不会自动添加 replace，但会校验并更新 go.sum
go mod tidy 不负责写入 replace，它只做两件事：补全缺失依赖、校验本地路径合法性。一旦发现右侧路径无效（比如没有 go.mod 或 module 名不匹配），它会静默跳过该 replace 行，继续用远程版本。
- 手动添加
replace后，必须运行go mod tidy触发校验 - 成功时，
go.sum会被更新，新增类似github.com/user/lib v0.0.0-00010101000000-000000000000 h1:...的记录 - 失败时，
go.mod不变，go.sum不变，构建仍走远程——这是最易被忽略的“无声失败” - IDE（如 VS Code）可能缓存旧状态，改完
go.mod后建议重启 Go extension 或执行go mod vendor强制刷新
真正卡住人的往往不是语法，而是模块路径的大小写、go.mod 文件是否存在、以及相对路径是否真的从 go.mod 所在目录可抵达——这些细节不满足，replace 就只是文件里的一行普通文本。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
