Go modules replace用 go.work 管理多模块开发的组织方式

多模块开发里最容易混淆的一点，是把 go.work 当成了要提交给所有环境的长期依赖配置。更稳妥的做法是：用 go.work 把本地模块临时组织到一起，用工作区级 replace 指向正在修改的目录；准备发布时，再让业务模块回到明确的版本依赖。这样既能联调，又不会把本机目录带进生产构建。

先分清 go.mod replace 与 go.work 的职责

如果只有一个模块需要临时指向本地目录，go.mod 的 replace 就够了；当业务模块和公共模块需要同时参与开发时，把多个模块加入 go.work 更清晰。工作区会把这些模块视为主模块，开发者可以跨目录修改代码并一起构建。

这里的关键边界是“本地开发上下文”。go.work 不是依赖发布清单，尤其不要把个人电脑上的相对路径当成部署配置。团队协作时应明确是否提交它；若只是个人联调，可以通过 GOWORK=off 检查脱离工作区后的真实模块状态。

用 go.work 把本地模块组织成开发工作区

假设目录中有 service 业务模块和上一级的 shared 公共模块，可以在它们的共同父目录创建工作区：

# 在两个模块的共同父目录初始化工作区
go work init ./service

# 把正在修改的公共模块加入工作区
go work use ../shared

# 查看当前工作区文件
cat go.work

生成的 go.work 通常包含 go 指令和多个 use 路径。use 指向的是包含 go.mod 的目录，不是某个源码文件。模块目录不必全部位于同一仓库，但路径关系应当稳定，避免在不同开发机上出现只有某个人能解析的相对路径。

让 replace 只承担开发期替换

当业务模块仍然依赖 example.com/shared v1.2.0，但当前要联调本地 ../shared 时，可以在工作区写替换：

# 将工作区内的 shared 版本替换为本地目录
go work edit -replace example.com/shared=../shared

# 也可以直接查看规范化后的 go.work 内容
go work edit -fmt

工作区级 replace 对同模块或同版本的 go.mod 替换具有更高优先级。这个覆盖关系很方便，但也容易造成误判：你在业务模块里看到的是版本依赖，实际构建却来自本地目录。因此建议把“本地替换”限制在开发工作区，不要把未经过评审的路径替换带入发布流水线。

用三个命令检查当前解析来源

排查“明明改了 shared，业务模块却没变化”时，先确认当前命令是否启用了工作区，再看模块列表，最后决定是否同步依赖：

# 先确认当前命令是否落在预期工作区
go env GOWORK

# 查看模块解析结果，重点观察 shared 的版本或本地替换
go list -m all

# 需要把工作区依赖要求写回各模块时再执行同步
go work sync

如果检查结果和预期不一致，不要先连续修改多个 replace。先确认当前目录、GOWORK 值和工作区中的 use 路径，再判断是路径问题、模块路径不一致，还是工作区覆盖了模块文件中的替换。

发布前收拢工作区边界

本地联调完成后，公共模块要么发布一个可追踪版本，要么在明确的构建环境中使用经过评审的替换。可以先关闭工作区做一次对照检查：

# 临时关闭工作区，检查业务模块的独立依赖状态
GOWORK=off go list -m all

# 在业务模块中确认依赖版本已经指向准备发布的版本
go get example.com/shared@v1.2.0+
# 整理模块文件，避免把无关依赖带入提交
go mod tidy

对照检查能发现两类常见问题：只在本地 ../shared 中存在的改动，或工作区级替换掩盖了业务模块缺少真实版本依赖。修复后再提交 go.mod、go.sum 和团队约定的工作区文件，开发配置与发布配置就有了清楚的分界。

相关问题

go.work 一定要提交到 Git 吗？

不一定。团队若约定统一的多模块目录结构，可以提交；个人临时联调则可不提交，并用 GOWORK=off 做发布前检查。

为什么 go.mod 里的 replace 没有生效？

先检查是否启用了工作区。相同模块或版本的 go.work replace 会覆盖模块级替换，这是最常见的原因。

go work use 会递归加入所有子模块吗？

普通 go work use 只加入指定模块目录；需要递归扫描子目录时使用 go work use -r，但仍应确认每个被加入的目录确实适合当前工作区。