Go replace 仅本机生效的发布配置

go.mod 的 replace 不是把本机依赖源码随库一起发布的机制。应用作为主模块构建时可以使用自己的替换规则，但指向本地目录的目标必须在构建环境存在；库被别人依赖时，它的替换规则不会自动传递给消费者。发布配置应当依赖真实可获取的版本，或明确交付完整的构建目录。

官方文档：https://go.dev/ref/mod#go-mod-file-replace

变化一句话：本地替换不是可分发的依赖版本

需要调整的是项目的发布配置，不是等待 Go 自动上传相邻目录。以一个报表应用为例：reportapp 联调尚未发布的 reportcore，开发机上的两个仓库互为邻居，于是应用增加本地 replace。这个安排适合本机协作，却没有说明干净构建机如何取得相同源码。

最小示意配置如下。所有 example.com 模块名和版本号均为说明用途，不代表真实项目或已发布版本；go 版本行也只是本示例选择的配置。

module example.com/reportapp

go 1.23.0

// 示例路径与版本用于说明，不能当成已发布依赖直接下载。
require example.com/reportcore v0.4.1

// 仅联调：此目录必须在执行构建的环境中真实存在。
replace example.com/reportcore => ../reportcore

如果修复后的 reportcore 已经发布为真实可获取版本，应用可以移除本地替换并更新 require。示意结果如下：

module example.com/reportapp

go 1.23.0

// 假设修复已发布为该版本；实际应改成项目真实可获取的版本。
require example.com/reportcore v0.4.2

不要只把右侧目录换成一个看似合理的版本号。版本必须实际存在，构建身份必须有权取得它，应用代码也必须与该版本兼容。这些条件由项目交付过程确认。

为什么改：主模块决定替换关系

replace 的作用是在当前主模块配置中改变模块来源；依赖模块里的 replace 会被忽略。替换规则本身也不增加模块依赖，相关模块仍需被 require 引入。工作区还可能参与决定本次使用的本地模块。

因此同一个 reportcore 在两种场景中的角色不同：开发者在其目录中操作时，它可以是主模块；下游应用引用它的发布版本时，它只是依赖。不能把前一种场景里的替换作用域带到后一种场景。

本文使用的是原创联调情境，没有声称某个生产事故已经发生。我会先确定“谁是本次主模块”，再看路径和版本；这样比反复清理模块缓存更容易找到作用域问题。

对旧代码的影响：路径、工作区与依赖身份

本地替换常见的问题是构建目录不完整：Docker 构建上下文只包含 reportapp，而相邻 reportcore 根本没有进入镜像构建阶段。改成绝对路径也只会绑定另一台机器的目录，不会让源码自动出现。

工作区则可能掩盖版本差异：代码使用了本地新增接口，但 go.mod 仍要求旧版本。关闭工作区后若出现接口缺失，应更新真实依赖版本或调整代码，而不是给使用者追加个人目录。

迁移建议：分别处理应用和库

应用团队可以选择两条明确的交付方式：优先使用已发布依赖版本；或将多模块源码作为受控构建输入一并提供。后一种方式可以保留本地替换，但构建说明必须包含目录关系、各仓库修订和获取方式，不能只提交一条 replace。

库维护者则应让发布源码与 require 中可获得的依赖保持一致。如果修复仍只存在于本地分支，应先将修复纳入可发布依赖，或明确调整库的依赖设计。让每个下游都手工复刻开发目录，会把维护成本扩散给消费者。

若决定长期依赖一个分叉，应把模块身份、导入路径与版本维护作为设计决策。replace 方便来源调整，却不替团队解决兼容性、授权访问或维护周期，也不说明下游是否愿意采用相同替换。

已有发布标签不要通过覆写源码来“补上本地修复”。官方模块发布指南要求对已发布内容保持稳定；修复应形成新版本，再让消费者显式升级。

最小检查：在独立消费者中确认真实依赖

下面是阅读者可在自己的项目中采用的检查命令，本文未执行，也未生成构建成功报告。路径、包范围及环境访问条件应按真实项目调整。

# 在应用或库模块根目录执行，先了解本次使用的配置。
go env GOMOD GOWORK

# 关闭工作区不会删除 go.mod 中的 replace。
GOWORK=off go list -m -json all

# 先按真实依赖更新配置，再在单模块模式整理并检查。
# tidy 可能修改 go.mod/go.sum，需审阅并提交相应变更。
GOWORK=off go mod tidy
GOWORK=off go test ./...
GOWORK=off go build ./...

观察模块列表中是否还有 Replace 信息及本地 Dir。GOWORK=off 只排除工作区影响，不会移除当前 go.mod 的替换规则。因此“关闭工作区后通过”仍不能直接说明没有本地替换依赖。

库的自测通过也不能完全代表下游场景。可以建立一个位于开发工作区之外的临时消费者，只要求待发布的真实版本，导入必要包，再执行其构建与测试。临时消费者不应复制库作者的个人 replace，否则失去了检查发布契约的意义。

对应用而言，更合适的补充是按照发布脚本在干净目录构建，确保每个本地来源都属于声明过的输入。清理全局缓存不是首要动作；先确认配置作用域、目标版本和目录是否正确。

常见问题：require、版本和本地联调

删除 replace 后找不到新接口，是缓存没有刷新吗？

优先确认 require 选择的真实版本是否包含接口。之前本地目录可能有尚未发布的修改，删除替换只是让这项差异暴露出来。

把库的 go.mod 一起发布，消费者为何仍不替换？

文件存在不等于其中每条指令对下游生效。依赖库的替换规则不承担消费者主模块的配置职责。

本地联调是否完全不能用 replace？

可以使用。关键是把联调约定和发布契约分清：本机源码能够获取、发布依赖也能独立获取，且两者差异有人负责消除。

资料：Go 模块替换规则；工作区规则；模块发布指南。