go mod edit -replace 需配合 go mod tidy 才生效，否则仅修改 go.mod 而不刷新缓存；路径须为绝对路径或 module path，Windows 下禁用反斜杠；replace 后需清理 go.sum 旧校验和并确保团队统一执行 tidy。
go mod edit -replace 为什么没生效
常见现象是执行 go mod edit -replace old=local/path 后，go build 仍拉远程模块，本地修改不被加载。根本原因是：这条命令只改 go.mod 文件，不触发 vendor 或缓存刷新，且必须配合 go mod tidy 才能真正落地。
- 执行后务必跟一句
go mod tidy，否则replace可能被后续依赖解析忽略 - 如果项目已启用
GOPROXY=direct或设置了其他代理，replace仍有效，但某些 IDE（如 VS Code + gopls）会绕过它做自己的模块解析，需重启 gopls 或加//go:build ignore临时规避 -
replace目标路径不能是相对路径（如../mylib），必须是绝对路径或 module path，否则go mod tidy会报错invalid replace directive path
用 go mod edit -require 添加依赖时的版本陷阱
直接运行 go mod edit -require=github.com/sirupsen/logrus@v1.9.0 看似加了依赖，但实际可能引入不兼容行为——因为 go mod edit 不校验该版本是否存在、是否满足当前 Go 版本约束，也不检查间接依赖冲突。
- 推荐先用
go get github.com/sirupsen/logrus@v1.9.0，再让go mod tidy自动写入require，这样会同步处理indirect标记和版本对齐 - 若坚持用
go mod edit -require，之后必须立刻跑go mod tidy -v，观察输出里有没有downgraded或upgraded提示，有说明版本被重写了 - 注意
@latest在私有模块或未打 tag 的仓库中可能指向 commit hash，导致不同机器结果不一致，生产环境应避免
go mod edit -json 输出结构怎么看
go mod edit -json 是调试依赖图最直接的方式，但它输出的是原始 JSON，字段含义不直观，容易误读 Replace 和 Indirect 的作用范围。
-
Require数组里的每个对象，Indirect: true表示该依赖不是你直接import的，而是被其他模块带进来的；删掉它可能破坏构建，别手抖 -
Replace字段只在显式配置了-replace时出现，它的New.Path是替换目标，New.Version为空时才表示本地路径替换 - 想快速查某个模块是否被 replace，用
go mod edit -json | jq '.Replace[] | select(.Old.Path == "github.com/example/lib")'（需装 jq），比肉眼扫快得多
Windows 下 go mod edit 路径分隔符问题
在 Windows 上用 go mod edit -replace 指向本地目录时，如果路径含反斜杠（\），会导致 go build 报错 invalid module path 或静默失败——Go 工具链内部统一用正斜杠解析模块路径，反斜杠会被当作非法字符。
立即学习“go语言免费学习笔记（深入）”；
- 一律用正斜杠：
go mod edit -replace example.com/lib=C:/work/mylib，哪怕在 CMD 或 PowerShell 里也要这么写 - 不要用环境变量拼接路径，比如
%USERPROFILE%\go\src\...，go mod edit不展开变量 - 如果路径含空格，必须用双引号包裹整个
-replace参数：go mod edit "-replace example.com/lib=C:/Users/John Doe/mylib"
真正麻烦的不是语法，而是 replace 后忘记删 go.sum 里的旧校验和，或者多人协作时有人提交了没 run go mod tidy 的 go.mod，导致 CI 构建失败。这些细节不报错，但会让问题延迟暴露。
