Go 模块怎么用 replace 临时测试本地依赖分支

依赖库已经修了一半，直接发版本又太早，最省事的办法通常不是改 import，而是在主模块的 go.mod 里临时使用 replace。它可以把 example.com/metrics 的代码指向工作区旁边的本地目录，调用方仍然照常导入原路径；测试完成后删除这一行即可。

本地分支测试的关键是“左侧保留被 require 的模块路径，右侧指向包含 go.mod 的本地模块根目录”，并在结束时恢复 replace。replace 只改变来源，不负责把依赖加入模块图。

replace 临时改变了模块来源，不改变导入路径

假设主模块是 example.com/orders，依赖模块是 example.com/metrics。依赖分支放在主模块同级目录的 ../metrics，其中必须有自己的 go.mod：

module example.com/metrics

go 1.23

主模块仍然保留原来的依赖声明，只增加本地替换：

require example.com/metrics v0.0.0-dev

// 临时把依赖切到相邻目录，import 路径保持不变
replace example.com/metrics v0.0.0-dev => ../metrics

这里的 v0.0.0-dev 只是左侧版本标识，右侧是文件路径，所以不写版本。若只写 replace 而没有匹配的 require，它不会自动把模块放进依赖图。另一个容易忽略的条件是：../metrics/go.mod 的 module 行必须仍是 example.com/metrics，不能为了本地分支临时改成另一个路径。

把依赖分支接入当前工作区

先在依赖目录切到要验证的分支，再回到主模块目录执行编辑命令。这样分支选择和模块替换各自有明确的修改点：

# 先在依赖模块中选择要测试的分支
cd ../metrics
git switch feature/decimal-rounding

# 回到主模块，用 Go 工具写入 replace，避免手改格式
cd ../orders
go mod edit -replace=example.com/metrics@v0.0.0-dev=../metrics

# 让工具重新整理模块文件
go mod tidy

分支名只是 Git 操作示例，实际项目应换成团队约定的分支。go mod tidy 可能改变 go.mod 或 go.sum，因此本地试验前最好先确认工作区没有未保存的依赖修改。若依赖模块目录不是主模块的相邻目录，可以使用其他相对路径或绝对路径，但共享代码时相对路径更容易暴露问题，提交前应删除。

用模块信息确认本地分支确实生效

不要只凭编译成功判断。编译器能找到同名的远程版本，并不代表用了你刚切换的目录。下面的命令会显示替换后的模块信息：

# 查看 Go 解析后的模块来源和本地目录
go list -m -json example.com/metrics

# 确认当前使用的 go.mod，以及是否处于 workspace 模式
go env GOMOD
go env GOWORK

重点看返回对象中的 Replace 和 Dir：Dir 应指向 ../metrics 的绝对路径，Replace 应保留原模块与本地模块的对应关系。若 GOWORK 返回了 go.work，还要检查其中是否使用了该目录，或存在同模块的 workspace 级 replace；workspace 的替换规则可能覆盖模块文件里的同类配置。

测试结束先删除 replace，再检查提交差异

验证完成后，回到主模块删除精确的替换规则：

# 删除临时本地替换
go mod edit -dropreplace=example.com/metrics@v0.0.0-dev

# 依赖图有变化时再整理；不要无条件覆盖别人的修改
go mod tidy

# 提交前确认临时路径已经消失
git diff -- go.mod go.sum

如果团队本来就依赖远程版本，差异里不应再出现 => ../metrics。若 go.sum 有变化，先判断它是不是本次依赖恢复造成的，再决定是否保留。更稳妥的做法是把“切换分支、添加 replace、验证来源、删除 replace”作为一次短生命周期实验，不把本地绝对路径带进共享分支。

常见问题

为什么 replace 写了却没有生效？

先确认左侧模块版本与 require 完全匹配，再确认右侧目录存在 go.mod，且 module 路径没有改变；最后检查 go.work 是否覆盖了规则。

本地目录能不能不写 require？

不能把 replace 当作新增依赖。模块图仍需要一条匹配的 require，否则替换规则没有对象可替换。

测试分支需要修改 import 路径吗？

通常不需要。只要分支仍属于同一个模块路径，调用方继续使用原 import；改变 module 声明反而会制造另一套依赖身份。