项目应使用 replace 还是发布预览版本来联调依赖

项目联调依赖时，我通常把判断标准定得很简单：依赖代码还在本机快速改动、只需要当前主项目验证，就用 replace；需要让 CI、测试环境或另一位开发者拿到同一份可下载代码，就发布 alpha/beta 预览版本。两者不是“谁更高级”的关系，而是分别对应本地闭环和跨环境闭环。

官方参考：https://go.dev/ref/mod

本地 replace 解决“马上改、马上试”，预览版本解决“版本固定、别人可复现”。先按联调边界选方案，合并前再检查 go.mod 是否留下了不该提交的本地路径。

• 本机同仓或相邻目录快速迭代：优先 replace。
• 跨机器、CI 或需要反馈的试用：优先预览版本。
• 两者都要确认 require 和实际构建图，不能只看 import 是否能编译。

先把联调问题分成两种闭环

如果依赖模块还没有发布，Go 官方建议先在调用方通过本地目录引用它。这个阶段的反馈重点是 API 形状、参数语义和调用链是否正确，开发者往往会连续修改依赖代码。此时发布多个临时版本会增加标签、代理缓存和回滚管理成本，replace 更直接。

当问题变成“让测试环境复现某个提交”“让其他人独立下载验证”时，本地路径就不够了。预览版本把代码变成模块生态可以获取的版本，但 alpha/beta 不是普通稳定版本，使用者需要明确指定版本号，不能期待 go get 自动把它选出来。

本地 replace 适合快速改动，但它只对主模块生效

主项目仍然保留原模块路径，右侧改成本地目录即可。被替换的目录必须有自己的 go.mod，并且 module 路径要和左侧路径匹配；只写 replace 不会自动把依赖加入模块图，因此通常仍需要一条 require。

module example.com/app

go 1.23

require example.com/payment v0.0.0-replace

// 联调期间把依赖指向相邻目录，import 路径保持不变。
replace example.com/payment v0.0.0-replace => ../payment

这份配置适合主项目和依赖模块在同一台机器上协作。验证时先执行：

# 查看主模块最终采用的依赖和替换关系
go list -m all

# 检查模块图，确认替换没有带来意外的依赖升级
go mod graph

要注意，replace 只在当前主模块的构建中发挥作用，依赖你的模块的下游项目不会自动继承这条规则。因此它不能当作对外发布方案。

预览版本适合跨环境复现，但要显式指定版本

当依赖代码已经能被打包并上传到仓库时，可以打一个带预发布标识的版本，例如 v0.4.0-beta.1。调用方显式获取它：

# 显式选择预览版本，避免默认版本选择忽略 alpha/beta
go get example.com/payment@v0.4.0-beta.1

# 整理 require 与 indirect 依赖记录
go mod tidy

预览版本的价值在于版本、提交和构建环境之间有可复现的关联；代价是每次反馈要重新发布版本，且调用方需要更新 go.mod。若当前仓库已经有正式版本，Go 默认倾向于选择正式版本，所以不能只说“仓库里有 beta”就认为测试环境会用到它。

用三个检查点决定最终方案

合并前可以按这个顺序收口：第一，搜索主项目和工作区文件中的 replace；第二，用 go list -m -json all 看实际的 Replace 字段；第三，如果要发布预览版本，确认 go.mod 中的版本号和 CI 使用的版本一致。准备正式发布时，删除临时本地替换，让构建回到可下载的模块版本。

两个容易混淆的边界

第一，replace 不是 fork 发布，也不会改变 import path；它只是改变当前主模块寻找代码的位置。第二，预览版本也不是稳定承诺，尤其是 v0 版本仍可能发生不兼容变化，应该配合变更说明和回归用例使用。

如果团队正在同一仓库内同时改主项目和依赖，优先用 replace 缩短反馈回路；如果问题需要在干净机器上复现，尽早切到预览版本。最终方案不在于永远只选一种，而在于让联调对象和可复现边界保持一致。

常见追问

replace 是否可以不写 require？不建议。replace 本身不会把模块加入构建图，主模块仍需要 require 一条被替换的模块版本。

预览版本能不能直接当正式依赖提交？可以提交，但要明确它仍是预发布版本，并在 CI 中固定同一版本；如果接口还会变化，先保留迁移说明和回滚版本。