replace 指令仅对包含 go.mod 的当前模块生效，需确保在模块根目录执行命令、replace 左侧与 import 路径严格一致、右侧为可读本地路径且含有效 go.mod。
replace 指令不生效？检查 go.mod 是否在正确目录
Go 的 replace 只对当前模块（即包含 go.mod 的目录及其子目录）生效。如果你在项目根目录执行 go build，但 go.mod 实际在 cmd/ 或 internal/ 子目录里，replace 就不会被加载。
- 运行
go list -m确认当前模块路径，输出应为类似example.com/myapp，而不是main或空字符串 - 如果输出是
command-line-arguments，说明没在模块根目录，replace完全被忽略 - 常见误操作：在 IDE 终端里 cd 错了目录，或用 VS Code 的“在终端中运行”默认打开了项目外的路径
replace 路径写错导致构建失败：本地路径 vs 远程导入路径
replace 左侧是模块名（即代码里 import 用的路径），右侧是本地文件系统路径，二者语义完全不同，不能混用。
- 错误写法：
replace github.com/user/pkg => ./pkg—— 如果你实际 import 的是github.com/user/pkg/v2，这条不会命中 - 正确写法必须严格匹配 import 路径：
replace github.com/user/pkg/v2 => ../local-pkg-v2 - 右侧路径支持相对路径（推荐）或绝对路径，但不能是
file://或git@地址 - 如果本地包没有
go.mod，Go 会尝试读取其go.sum或 fallback 到伪版本，可能触发invalid version: unknown revision
go mod tidy 清掉 replace？因为模块校验失败
go mod tidy 会尝试下载左侧模块的真实远程版本，并比对 checksum。如果本地替换路径下内容与远程模块不兼容（比如缺少 go.mod、版本号不一致、或 go.sum 冲突），它可能静默丢弃 replace 并报错。
- 先运行
go mod graph | grep 'your-module-name'，确认依赖图中是否还存在该模块 - 若已消失，立即执行
go mod edit -replace=github.com/x/y=../y手动加回，再go mod download - 更稳妥的做法：在本地包根目录运行
go mod init github.com/x/y（确保模块名与 import 一致），并提交go.mod - 避免在 CI 中依赖
replace：CI 环境通常没本地路径，应改用go mod edit -replace+git submodule或私有 proxy
调试 replace 是否真正生效：看编译时实际加载的源码路径
光看 go build 不报错，不代表你的修改被用了。最直接的办法是让编译器暴露实际加载位置。
立即学习“go语言免费学习笔记（深入）”；
- 在引用该包的代码里加一行：
fmt.Printf("pkg path: %s\n", runtime.FuncForPC(reflect.ValueOf(yourFunc).Pointer()).File) - 或使用
go list -m -f '{{.Dir}}' github.com/user/pkg，输出应为你replace指向的本地路径 - 如果输出是
$GOPATH/pkg/mod/cache/download/...，说明replace没生效，或者你 import 的是另一个变体（如带/v2后缀） - 注意：IDE（如 GoLand）的跳转和自动补全有时会缓存旧路径，重启 Go module index 或清空
~/.cache/go-build更可靠
replace 的核心约束就两条：模块名必须字面匹配 import 路径，本地路径必须可读且含有效模块定义。其他所有问题，基本都是这两条没对齐。
