replace必须写在当前项目（主模块）的go.mod中才生效，仅对当前模块起作用；被替换模块自身的go.mod中声明无效，且右侧本地路径需存在有效go.mod文件且module名与左侧完全一致。
replace 写在哪个 go.mod 里才生效
只写在当前项目（主模块）的 go.mod 文件里才管用。写在被替换模块自己的 go.mod 中，对你的项目完全无效——Go 不会“跨模块读取 replace 规则”。
常见错误是：看到某个间接依赖出问题，就跑去它的源码目录改它的 go.mod，加了一条 replace，结果 go build 照样拉远端、报错照旧。
-
replace必须出现在你执行go build所在目录的go.mod中（即顶层模块） - 如果项目有多个子模块（如
./service、./pkg/utils），每个子模块都有自己的go.mod，但只有主模块的go.mod里的replace能影响整个构建 - 子模块若要调试本地代码，也得由主模块统一
replace，不能靠子模块自己声明
本地路径必须满足三个硬性条件
replace github.com/foo/bar => ./local-bar 这行看似简单，但任一条件不满足，Go 就静默忽略整条规则，回退到原始远端依赖——不会报错，只会让你以为“没生效”。
Go语言（Golang）1.26.0
下载
Go语言（Golang）1.26.0版本提供 Go 官方 Windows amd64 MSI 安装包下载入口，版本号 1.26.0，可用于旧项目维护、兼容性测试和指定版本开发环境配置。
- 右侧路径（
./local-bar）必须存在，且是相对于主模块go.mod所在目录的合法路径（不能是../outside，除非你真需要且该路径下有完整模块） -
./local-bar目录下必须有go.mod文件，且其第一行module声明必须与replace左侧**完全一致**（包括大小写、斜杠、版本后缀，如v2.1.0） -
./local-bar/go.mod不能是空文件或仅含module行；至少要有go行或一个require，否则 Go 认为它未初始化，跳过加载
间接依赖怎么替换
你的代码没直接 import 某个包，但它被上游依赖带进来（标记为 // indirect），这时 replace 依然有效，但必须先确认它真实存在于依赖图中。
- 运行
go mod graph | grep 'bad/pkg'，看谁引入了它；如果没输出，说明它根本没参与构建，不用替换 - 只要它出现在
go list -m all输出里，就可以在主模块go.mod中直接写replace，Go 会在解析阶段重映射路径 - 不要试图用
require bad/pkg v1.2.3“覆盖”间接依赖——Go 不允许 require 未直接 import 的模块，go mod tidy会删掉它 - 若多个间接依赖来自同一模块的不同版本，
replace会统一指向你指定的本地路径，不区分版本
CI 和多环境部署时 replace 为什么炸了
replace 指向 ./local-path 是开发期便利机制，不是部署方案。CI 机器上不存在这个路径，go build 直接失败，这不是 bug，是设计如此。
- 上线前必须手动删除或注释掉所有本地
replace行，改用语义化版本（如require github.com/foo/bar v1.2.3） - CI 流程中建议加一步检查：
grep -q "=> \." go.mod && echo "ERROR: local replace found" && exit 1 - 如果真需跨环境共享本地修改，应走私有 proxy 或发布预发布 tag，而不是依赖文件系统路径
-
go.work可缓解多模块开发时频繁改replace的麻烦，但它不解决部署问题——go.work文件本身也不进 CI
真正难的不是写对 replace，而是判断该不该用它。当出现多层引用报错，先跑 go mod graph 看清依赖流向，再决定是修上游、抽公共包，还是临时用 replace 隔离验证。本地路径替换后，IDE 可能缓存旧状态，go mod tidy 后记得重启 gopls 或刷新 workspace。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
