replace语句需显式声明原始模块路径与本地绝对或根相对路径，执行go mod tidy或go build后生效，go list -m all仍显示原模块名，验证需用go mod graph或go build -x查看实际路径。

go.mod 中 replace 语句怎么写才生效

本地模块替换必须在 go.mod 文件中用 replace 显式声明，且仅对当前模块及其依赖生效。Go 不会自动扫描本地路径，也不会 fallback 到本地目录。

• replace 左侧必须是模块路径（即被依赖的原始 module path），和 require 中声明的一致，不能是相对路径或别名
• 右侧必须是绝对路径（推荐）或相对于当前 go.mod 的相对路径；若用相对路径，开头不能带 ./，Go 会报错 invalid replace directive: must be absolute or root-relative
• 执行 go mod tidy 或 go build 后，Go 才会实际拉取并缓存替换后的模块；但不会自动检测本地代码变更，改了本地源码需手动触发重建

替换后为什么 go list -m all 不显示本地路径

go list -m all 显示的是模块“逻辑标识”，不是物理路径。即使用了 replace，它仍显示原始模块名（如 github.com/user/lib），只是背后加载的是你本地的代码。

• 验证是否真正生效：运行 go mod graph | grep your-module-name，看依赖图中该模块是否指向你的本地路径
• 更直接的方式是加 -x 参数编译：go build -x，观察日志里 cd /path/to/your/local/module 是否出现
• 注意：go mod vendor 会把 replace 后的本地代码复制进 vendor/，此时路径就固化为副本，不再联动本地编辑

replace 指向子模块或未定义 go.mod 的目录会怎样

Go 要求 replace 右侧路径下必须存在有效的 go.mod 文件，否则构建失败，报错类似 no Go source files in /path/to/dir 或 cannot find module providing package。

• 如果目标目录没有 go.mod，先在其中运行 go mod init example.com/local（模块名可任意，只要不冲突）
• 不建议 replace 到某个子目录（如 ../lib/core），除非该子目录本身就是一个独立模块（含自己的 go.mod）
• 若原模块使用了 replace 或 retract 等高级特性，本地替换后这些策略会被忽略——本地 go.mod 完全接管

replace github.com/example/old => /Users/me/src/github.com/example/new

路径错误、模块缺失、未运行 go mod tidy 是三个最常卡住的地方。替换不是软链接，也不是 IDE 设置，它只在 Go 的模块解析阶段起作用，且每次构建都重新检查 —— 所以改完 go.mod 一定要重试命令，而不是只刷新编辑器提示。