replace语句必须写在go.mod文件中且仅对当前模块生效，用于依赖重定向，不被下游继承；旧路径须与require完全一致，新路径需含有效go.mod；调试时是唯一可靠本地覆盖方式，上线前必须移除。
replace 语句必须写在 go.mod 文件里，且只对当前模块生效
Go 的 replace 不是运行时或构建时的命令行开关，而是模块依赖重定向机制，只在 go.mod 中声明才起作用。它不会影响其他模块对你的模块的引用方式，也不会被下游模块继承。
常见错误是试图在 go build 或 go run 时用参数“临时替换”，这是无效的——Go 模块系统不支持运行时路径覆盖。
-
replace后面的旧路径必须和require中声明的模块路径**完全一致**（包括版本号，如果 require 带了@vX.Y.Z） - 新路径可以是本地绝对路径（如
/home/user/mylib），也可以是相对路径（如../mylib），但必须包含有效的go.mod文件 - 若本地模块没有
go.mod，执行go mod tidy会报错：no required module provides package ...
调试本地模块时，replace + local file path 是唯一可靠方式
当你修改一个本地依赖模块（比如 github.com/you/utils），又想立刻在主项目中验证效果，replace 是绕过远程拉取、强制使用本地代码的唯一标准做法。
module example.com/app
go 1.22
require (
github.com/you/utils v0.1.0
)
replace github.com/you/utils => ../utils
注意：../utils 目录下必须有 go.mod，且其 module 声明应为 github.com/you/utils（或与 require 行完全匹配）。否则 go build 会找不到包。
- 路径是相对于
go.mod所在目录计算的，不是相对于当前 shell 路径 - Windows 下使用正斜杠
/或双反斜杠\均可，Go 内部自动标准化 - 不要在
replace后加版本号（如=> ../utils v0.1.0），语法错误
replace 不会改变 go.sum，但可能引发校验失败
go.sum 记录的是 require 行声明的模块版本的哈希值，不是 replace 后实际加载的代码。所以即使你用 replace 指向了本地未提交的修改，go build 仍能通过，但 go mod verify 会失败，因为本地内容与 go.sum 不符。
- 开发调试阶段可忽略
go mod verify报错，它只是提醒“当前代码和原始发布版本不一致” - 上线前务必移除
replace，改用真实发布的 tag，并运行go mod tidy && go mod vendor确保可重现 - 若需保留调试痕迹，可在
go.mod中用// debug: replace in use注释，避免遗忘
嵌套 replace 或跨多级目录时，路径容易算错
当主模块和被替换模块之间隔了不止一级目录（例如主模块在 ~/proj/app，被替换模块在 ~/proj/lib/core），相对路径很容易写成 ../lib/core 而不是正确的 ../../lib/core。
最稳妥的做法是：在主模块根目录执行 go mod edit -replace=github.com/you/core=../../lib/core，让 Go 工具自动计算并写入 go.mod，避免手误。
-
go mod edit -replace不会触发下载或校验，只改文件，安全 - 如果本地模块路径含空格或特殊字符，用引号包裹整个 replace 参数
- 多个 replace 可重复调用
go mod edit -replace，无需手动编辑
替换成本地模块这件事本身很简单，难的是路径精度、模块初始化完整性、以及上线前清理的纪律性——这三个点漏掉任何一个，都可能导致 CI 失败或生产环境行为不一致。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
