replace不是覆盖require，而是构建时路径重写：require声明保持不变，Go在解析依赖时将指定模块路径重定向至本地路径，需确保本地模块路径、go.mod中module名与replace左侧完全一致。
replace 不是“覆盖 require”，而是构建时路径重写
Go 的 replace 不会删除或修改 require 声明，它只在构建（go build、go run、go test）阶段临时重定向模块解析路径。也就是说：require github.com/user/lib v1.2.3 依然存在，但 Go 工具链在实际加载代码时，会把所有对 github.com/user/lib 的引用，替换成你指定的本地路径（比如 ./local/lib）。
这种重写发生在 module graph 构建阶段，不影响模块语义版本号，也不影响 go list -m 显示的“声明版本”——但 go list -m all 的输出里，该模块右侧会显示本地路径，这就是生效标志。
- 不运行
go mod tidy时，replace可能不被识别（尤其新增后首次使用） -
replace对go get无影响：执行go get github.com/user/lib仍会拉远程版本 - 如果本地路径下没有
go.mod，Go 会报错no required module provides package
本地路径必须是有效模块，且 module path 要匹配
被 replace 指向的本地目录，不是随便放个 .go 文件就行。它必须是一个合法 Go 模块，核心要求只有两个：
- 目录下有
go.mod文件 -
go.mod第一行的module声明，必须和replace左侧的模块路径完全一致（包括大小写）
例如主项目写了：replace github.com/myorg/utils => ./vendor/utils，那么 ./vendor/utils/go.mod 必须以 module github.com/myorg/utils 开头。哪怕只差一个字母或斜杠，Go 就无法关联，编译时会提示 cannot find module providing package。
立即学习“go语言免费学习笔记（深入）”；
常见错误是直接复制代码过去却忘了初始化：cd ./vendor/utils && go mod init github.com/myorg/utils 才算真正就位。
相对路径 vs 绝对路径：开发机协作时容易翻车
replace 支持相对路径（如 ../utils）和绝对路径（如 /home/you/code/utils），但强烈建议只用相对路径。
- 相对路径以主项目
go.mod所在目录为基准，可移植、可 git commit（只要团队约定好目录结构） - 绝对路径在别人机器上必然失效，CI 环境也几乎不可能匹配，属于“本地调试一时爽，提交之后全抓瞎”
- Windows 和 Linux 路径分隔符不同（
\vs/），但 Go 工具链内部统一处理/，所以一律用正斜杠即可
如果你看到同事的 replace 里写着 C:\dev\mylib 或 /Users/xxx/...，请立刻提醒他改成 ../mylib 并同步更新 README 中的开发约定。
replace 生效范围仅限当前 module，且不能跨 workspaces 自动传递
replace 是单 module 级别的配置，只影响定义它的那个 go.mod 文件。即使你用 go work use ./subproj 引入子模块，子模块自己的 replace 不会自动继承到 workspace 根；反过来，workspace 根的 replace 也不会透传给子模块——除非子模块显式声明。
- 多个子模块依赖同一个库？每个都要单独加
replace，或者统一用go work在 workspace 根管理 -
go run ./cmd从根目录执行时走 workspace 规则；但cd ./cmd && go run .就只看./cmd/go.mod，可能漏掉替换 -
replace不参与版本计算：即使你 replace 到 v2.0.0 分支，go list -m -f '{{.Version}}'仍返回原始require里的版本号
真正容易被忽略的是：replace 在测试、构建、vendor 时都生效，但在 go install 全局安装二进制时，如果目标不是当前 module，它可能根本不会被加载——这时候得靠 GOBIN 或显式 -modfile 控制。
