Go module replace 指向本地目录后发布构建为什么失败

如果 go.mod 里写着 replace example.com/shared => ../shared，开发机能编译并不奇怪：Go 只是把依赖解析到了当前文件系统中的另一个模块。发布构建失败的根因通常也在这里——压缩包、干净 checkout 或 CI runner 并没有这个相对路径。正式发布应使用可获取的模块版本；本地多模块联调则交给 go.work，不要让开发机目录意外成为交付物的一部分。

replace 为什么在本地好用，发布环境却失败

replace 的右侧如果是本地目录，Go 会从该目录读取模块内容；右侧目录通常还必须有自己的 go.mod。这条规则解决的是“当前主模块如何找到依赖”，不是“如何把依赖随发布物运输”。因此下面的配置在开发目录中可以成立：

module example.com/app; go 1.23; require example.com/shared v0.0.0-replace; // 临时把共享模块指向工作区旁边的本地目录; replace example.com/shared v0.0.0-replace => ../shared

当构建命令在 /workspace/app 执行时，../shared 可能正好存在；换成只包含 app 的 CI checkout 后，路径就变成了不存在的 /workspace/shared。此时常见报错会落在找不到模块目录、找不到包，或无法读取右侧模块的 go.mod。先检查路径和构建上下文，比盲目执行 go mod tidy 更有效。

如何判断 replace 是临时开发开关还是发布依赖

不要只看文件里有没有 replace，还要看它是否真的参与当前构建。先在项目根目录执行以下命令：

# 查看当前工作区覆盖和实际模块解析结果; go env GOWORK; go list -m -json all; # 只在确认需要时查看主模块中的 replace 文本; go mod edit -json

GOWORK 如果指向某个 go.work，说明当前命令可能在工作区模块图中运行；如果输出 off，则不会使用工作区文件。go list -m -json all 的模块信息里重点看 Path、Version、Dir 和 Replace：看到本机绝对目录或 ../ 路径，就说明当前结果仍依赖本地文件系统。

这也是判断“临时开关”的简单标准：如果发布命令不能在干净 checkout 中得到同样的 Dir 与模块版本，就不应把该 replace 当成正式依赖。还要注意，replace 只在主模块的模块图中生效；一个依赖模块自己的 replace 不会替发布方自动承担依赖运输。

用 go.work 和版本化模块把发布边界收紧

如果目标只是同时修改 app 和 shared，优先在仓库外或开发工作区创建 go.work：

# 在包含两个模块的工作区初始化 go.work; go work init ./app ./shared; # 后续新增一个本地模块时把它加入工作区; go work use ./tools

go.work 的 use 声明告诉 Go 哪些目录是当前工作区的主模块。这样本地联调的意图更清楚，也不必把 ../shared 永久写进 app 的发布用 go.mod。团队可以把工作区文件纳入开发约定，也可以让发布脚本明确使用 GOWORK=off，关键是本地和 CI 的选择要有意图而不是靠默认搜索。

真正发布时，把 shared 提交到可访问的仓库或模块代理，给 app 使用正式版本：

require example.com/shared v1.4.0; // 发布配置不再依赖开发机旁边的目录; // replace example.com/shared v1.4.0 => ../shared

如果正在验证 shared 的未发布修复，可以在开发分支暂时使用 replace；合并发布分支前删除它，或改成指向仓库中的可获取版本。这里的“删除”不是为了让工具安静，而是让依赖来源对构建机器可见、对审查者可追踪。

发布前检查清单：让 CI 复现真正的模块图

把检查放在构建前，至少确认以下四件事：

1. 干净 checkout 中没有依赖仓库外的 ../ 或本机绝对路径。
2. 执行发布命令时明确 GOWORK=off 或明确指定受控的 go.work。
3. 运行 go list -m all，确认关键模块有版本或可追溯的仓库来源，没有意外的 Replace。
4. 在与 CI 相同的网络和凭据条件下执行 go mod download、go build ./...，把失败留在构建阶段。

若确实要把本地模块一起发布，构建上下文必须显式包含它，并且打包结构与相对路径一致；这属于交付布局设计，不是单靠 replace 就能完成的功能。更稳妥的默认判断是：replace 用于联调，版本用于发布，go.work 用于组织本地多模块。

常见问题

replace 右侧能写绝对路径吗？

可以指向本地目录，但它会把机器路径带入模块解析，跨机器和 CI 更容易失效。团队配置应优先使用相对、可控的工作区方案或可获取的模块版本。

只提交 go.work 就能解决发布失败吗？

不能。go.work 解决本地多模块联调；发布仍要保证 CI 的工作区、模块版本和依赖来源可复现。不要让 CI 无意中读取开发机专用的工作区文件。

为什么 go mod tidy 后 replace 还在？

tidy 会整理依赖图，但不会替你判断本地替换是否适合发布。只要 replace 仍写在主模块配置里，它就可能继续影响解析，需要按发布策略主动移除或改为正式版本。