replace 指令必须写在 go.mod 文件末尾的 require 块之后，格式为 replace old/module/path => ./local/path，右侧须为以 ./ 开头的相对路径，且本地包 go.mod 中 module 名须与左侧完全一致。
replace 指令写在哪？必须在 go.mod 文件里
本地包替换不是命令行操作，也不是 go build 的参数，它只生效于 go.mod 文件中的 replace 语句。Go 工具链在解析依赖时，会优先按 replace 规则重写模块路径——这步发生在下载、构建、测试全过程中。
常见错误现象：go run main.go 仍用远端版本；go list -m all 显示未替换；IDE（如 VS Code）没识别本地修改——八成是 replace 写错位置或格式不合法。
-
replace必须放在go.mod文件末尾的require块之后，不能嵌在require里面 - 语法是
replace old/module/path => ./local/path，右边路径必须是相对路径（以./开头），不能是绝对路径或../跨父级目录（除非明确需要，且模块根目录匹配） - 如果本地包本身有
go.mod，它的module名必须和replace左边完全一致（包括大小写和版本后缀，如v1.2.3）
replace 后为什么还是拉远端？检查三个硬性条件
Go 不会“自动 fallback”，只要 replace 不满足任一条件，就彻底忽略该行，静默退回到原始依赖。这不是 bug，是设计使然。
- 本地路径下必须存在有效的
go.mod文件，且其中module行声明的路径与replace左侧完全一致（例如：replacegithub.com/user/lib=>./lib，则./lib/go.mod第一行必须是module github.com/user/lib） - 本地模块不能处于“未初始化”状态：执行过
go mod init，且至少有一个require或导出符号（空go.mod可能被跳过） - 项目主模块（即当前
go.mod所在目录）必须已执行过go mod tidy或至少一次go build，否则缓存未更新，replace不参与解析
调试时如何确认 replace 生效了？别信 IDE，看 go list
IDE 的依赖高亮经常滞后或误判，真正可信的是 Go 自己的模块解析结果。
立即学习“go语言免费学习笔记（深入）”；
运行 go list -m -f '{{.Path}} {{.Dir}}' github.com/user/lib（把 github.com/user/lib 替成你要查的模块名）。如果输出的 .Dir 是你本地路径（比如 /your/project/lib），说明已替换；如果还是 $GOPATH/pkg/mod/... 下的哈希路径，就是没生效。
- 加
-u=none参数可排除升级干扰：go list -m -u=none -f '{{.Path}} {{.Dir}}' xxx - 想看全部依赖映射关系？用
go mod graph | grep 'lib'，搜索关键词比翻长列表快 - 注意：
go build -v会打印实际编译的包路径，但只显示最终参与编译的，不反映模块解析阶段的替换逻辑
replace 不是开发模式开关，改完要重新 tidy
很多人编辑完 go.mod 就直接 go run，结果行为没变——因为 go.mod 文件变更不会自动触发依赖重算。Go 要求显式同步。
- 每次修改
replace后，必须运行go mod tidy（哪怕只是调整路径），否则旧缓存继续生效 -
go mod tidy会校验本地路径是否存在、go.mod是否合法，并更新go.sum（对本地替换，通常只加一行=> ./xxx校验记录） - 如果本地包接口变了，而主项目没重编译，可能因缓存导致“看似生效实则用旧代码”——此时加个
go clean -cache更保险
最麻烦的点其实不在语法：当本地包被多个上级模块同时 replace，而它们又互相依赖时，路径冲突和模块循环会悄无声息地让某一处失效。这种时候，go list -m all 输出里的重复路径就是第一个线索。
