replace必须写在当前项目go.mod中且仅对本模块生效，常见错误是误写入被替换模块自己的go.mod；需确保路径完全匹配、本地目录含有效go.mod、执行go mod tidy更新缓存。
replace 必须写在当前项目的 go.mod 里
很多人把 replace 写进被替换模块自己的 go.mod，结果发现完全没生效——这是最常踩的坑。replace 只对声明它的模块及其直接构建行为起作用，不会“穿透”到上游或下游模块。它不是全局开关，而是当前模块的本地解析规则。
你得打开自己项目的 go.mod 文件，在 require 块之后、module 声明之后的位置添加 replace 行。例如：
replace github.com/gorilla/mux => ./vendor/mux
常见错误包括：
- 误把
replace加到github.com/gorilla/mux自己的go.mod中 - 放在
require块内部（Go 不识别） - 路径写成绝对路径却没加
// +build ignore注释（CI 环境必然失败）
本地路径替换必须带 ./ 且目录下要有 go.mod
指向本地代码时，路径必须是相对当前项目 go.mod 所在目录的路径，且以 ./ 开头；更重要的是，目标目录下必须存在合法的 go.mod 文件（哪怕只有一行 module local/name）。否则 Go 会退回到 legacy 模式，忽略 replace 规则。
比如你想用本地修改的 github.com/user/log，结构如下：
myproject/
├── go.mod
└── vendor/
└── log/ ← 这里必须有 go.mod
那么 go.mod 中应写：
replace github.com/user/log => ./vendor/log
不能写成：
-
replace github.com/user/log => vendor/log（缺./） -
replace github.com/user/log => ./vendor/log/（末尾斜杠多余） -
replace github.com/user/log => /home/me/log（绝对路径不可移植）
远程替换要带明确版本，且 module 名必须一致
用 replace 指向另一个远程仓库（如 fork）时，右侧必须包含版本标识，比如 v1.2.3 或 master；同时，被替换模块自身的 go.mod 里声明的 module 名，必须和 replace 左侧的路径完全一致（大小写、斜杠、末尾都不容错）。
例如：
replace github.com/sirupsen/logrus => github.com/myorg/logrus v1.9.3
如果 github.com/myorg/logrus 的 go.mod 里写的是 module github.com/myorg/logrus/v2，那 Go 会拒绝加载——它只认左侧路径的字面匹配。
其他要点：
- 不能省略版本：
replace github.com/x/y => github.com/x/y是无效语法 - 不支持通配符：
github.com/x/* => ./local/*会被忽略 - 多个
replace匹配同一模块时，以文件中**最后一行**为准
间接依赖必须先拉进 require 才能 replace
如果你的项目没直接 import 某个模块，但它通过其他依赖间接引入（标记为 // indirect），那么仅在 go.mod 里加 replace 是无效的。Go 不会对未显式出现在 require 列表里的模块执行重定向。
解决办法是先把它“提级”进来：
go get github.com/problematic/lib@v0.1.0
或手动运行：
go mod edit -require=github.com/problematic/lib@v0.1.0
然后再加 replace 行。验证是否生效，可用：
go list -m all | grep problematic
看输出是否指向你期望的路径。注意：go mod tidy 必须执行，否则 go.sum 和缓存不会更新，构建仍可能走旧路径。
IDE 缓存也常干扰判断——Goland 或 VS Code 需手动触发 “Reload module” 或重启 Go language server，否则编辑器里看到的 import 提示和跳转仍是原始版本。
真正麻烦的地方不在语法，而在于模块名一致性、间接依赖的显式化、以及 IDE 缓存与构建缓存的双重滞后。改完 go.mod 后，别急着跑测试，先 go list -m all 确认路径，再清缓存、重载项目、最后 go build。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
