Go mod edit -replace 如何只在本地开发生效

本地调试依赖时，直接执行 go mod edit -replace 会改写目标 go.mod，这条替换关系很容易被提交并带进 CI。想让它只在本机开发生效，优先使用一个不提交的 go.work；单模块项目也可以复制出独立的 .mod 文件，再让测试显式读取副本。

官方文档：https://go.dev/ref/mod

先分清 replace 到底改了哪里

命令中的 -replace=旧模块=本地目录 是低层编辑操作。它会把替换写入指定的 go.mod，而不是只对随后一次编译生效；右侧本地目录还必须是一个包含 go.mod 的模块根目录。

# 这条命令会持久化修改当前模块的 go.mod
go mod edit -replace=example.com/acme/lib=../local-lib

# 查看修改后的 replace，确认它确实落在目标文件中
go mod edit -json go.mod

另一个常见误区是只写 replace 不写 require。替换指令本身不会把模块加入依赖图；项目必须已经通过 require 引用了对应模块，构建才会用上替换。版本写在左侧时只替换该版本，不写版本则覆盖这个模块路径的所有版本。

用 go.work 给本地替换单独划边界

需要同时修改主项目和邻近依赖时，工作区文件最直观。先在项目父目录或项目目录创建本地 workspace，再把两个模块加入其中：

# 创建只服务于本机联调的工作区文件
go work init
go work use .
go work use ../local-lib

# 把原模块路径指向本地模块根目录
go work edit -replace=example.com/acme/lib=../local-lib

# 确认当前命令是否正在使用这个 workspace
go env GOWORK

此时 Go 命令会在 workspace 上下文中解析本地替换，主项目的 go.mod 不需要增加 replace。把 go.work 和通常自动产生的 go.work.sum 加入本地忽略规则，避免误提交；如果项目已经有团队维护的 go.work，不要擅自覆盖，应先确认其中的模块和替换关系。

单模块项目用独立 modfile

如果项目不适合引入 workspace，可以保留共享 go.mod，复制一份本地文件，并在运行命令时明确指定它。文件名要以 .mod 结尾。

# 复制共享依赖定义，后续只编辑本地副本
cp go.mod go.local.mod

# 只给本地副本增加替换，不碰仓库里的 go.mod
go mod edit -replace=example.com/acme/lib=../local-lib go.local.mod

# 测试时显式选择本地依赖定义
go test -modfile=go.local.mod ./...

如果命令会写入依赖图，Go 还会按同名规则寻找旁边的 go.local.sum。因此在复制或清理本地副本时，要把配套的校验文件一起处理。这个方案的代价是每个需要使用替换的命令都要带 -modfile，忘记参数就会回到共享 go.mod 的解析结果。

提交和 CI 前的检查清单

# 提交前只查看依赖文件是否被意外修改
git diff -- go.mod go.sum

# CI 明确不读取本机 go.work，避免本地目录替换泄漏
GOWORK=off go test ./...

最后一次检查应回答两个问题：本地替换是否真的被当前命令使用，以及关闭 workspace 后项目是否仍能按仓库依赖构建。前者可看 go env GOWORK 和 go list -m，后者交给 GOWORK=off 的测试。不要把本地目录写进共享 go.mod，再指望发布时自动恢复。

常见问题

go.work 会自动影响仓库里的 go.mod 吗？

不会。它是独立的 workspace 配置，但当前目录及父目录能找到它时，Go 命令会进入 workspace 模式。

为什么加了 replace 仍然没有生效？

先确认左侧模块已被 require 引用，再检查当前命令是否读取了正确的 go.work 或 -modfile。

可以把本地目录放进 go.mod 再不提交吗？

可以作为个人临时操作，但很容易污染工作树或被误提交；需要稳定复用时，优先用未跟踪的 go.work 或显式 modfile。