replace指令必须配合法定module名使用，本地模块go.mod首行module声明须与replace左侧路径完全一致（含大小写、斜杠方向），否则静默忽略；推荐相对路径、禁用vendor模式、上线前必须清理。
replace 指令必须配合法定 module 名使用
本地模块的 go.mod 第一行 module 声明，必须与 replace 左侧的路径完全一致（包括大小写、斜杠方向、无多余空格）。比如主项目依赖 github.com/org/lib，那本地库的 go.mod 就得是 module github.com/org/lib，不能写成 github.com/org/lib/v2 或 github.com/org/Lib——否则 go mod tidy 会报 no matching versions 并静默忽略 replace。
常见错误现象：
-
go list -m all不显示本地路径映射，仍显示远程 tag 版本 -
go build报错import "github.com/org/lib": cannot find module providing package - 编辑器（如 VS Code）里能跳转、但运行时报
undefined: lib.Func
相对路径比绝对路径更可靠
在 go.mod 中写 replace github.com/org/lib => ../lib，比写 /home/user/go/src/lib 更安全。原因很实在：CI/CD 流水线或队友拉代码后，绝对路径必然失效；而相对路径基于 go.mod 所在目录计算，只要目录结构一致，go mod tidy 就能验证通过。
注意点：
立即学习“go语言免费学习笔记（深入）”；
- 路径必须指向含有效
go.mod的目录，不是随便一个文件夹 -
../lib是相对于主项目go.mod的位置，不是相对于当前 shell 路径 - 如果本地模块放在
./internal/lib，replace 路径就得是./internal/lib，不能省略./
伪版本不会影响构建，但会影响依赖可见性
本地模块没打 tag 时，Go 会自动生成伪版本（如 v0.0.0-20260804123456-abcdef123456），这本身没问题。但要注意：go list -m all 输出里，该模块会显示为 github.com/org/lib v0.0.0-... => ../lib；而如果你用 go mod graph 查依赖图，它仍以伪版本为节点名，不是 local 或 dev 这类标识——别误以为没生效。
真正容易被忽略的是：一旦你运行了 go mod vendor，本地 replace 不会被复制进 vendor/ 目录，go build -mod=vendor 会直接失败。所以 vendor 模式下不能依赖 replace。
上线前必须清理 replace 行
CI 构建环境没有你的本地路径，replace 会导致 go mod download 失败或 silently fallback 到旧版本。最稳妥的做法不是靠文档提醒，而是加一道检查：
- 在 CI 脚本开头加
grep -q "replace" go.mod && exit 1，让含 replace 的 PR 直接被拦截 - 用
//go:build !ci+// +build !ci条件编译控制某些仅开发期启用的 replace（需配合go mod edit -dropreplace自动化清理） - 永远不要把
replace提交到 main 分支；只保留在 feature 分支或本地 git stash 中
replace 是调试开关，不是部署方案。它的存在本身就意味着你还没准备好发布那个模块——要么打个预发布 tag，要么先把代码合入主干再同步 bump 版本号。
