Go workspace 怎么让多个模块共享本地开发版本

一个仓库里同时维护 client 和 shared 两个 Go 模块时，最省事的本地开发方式不是反复修改 client/go.mod 的 replace，而是在共同父目录建立 go.work。它把多个模块声明为当前工作区的主模块，client 可以直接用到 shared 尚未发布的本地改动。

本地用 go.work 管理并行开发，发布和 CI 仍以每个模块自己的 go.mod 为准。关键是验证工作区只覆盖本地命令，不把开发机上的路径悄悄带进正式构建。

先把多个模块放在清晰的目录边界里

假设目录如下，每个目录都能单独发布：

repo/
  client/
    go.mod       # module example.com/client
  shared/
    go.mod       # module example.com/shared

client 的源码可以导入 example.com/shared/format，但两个模块的 go.mod 仍然独立。不要把仓库根目录当成一个“超级模块”：go.work 负责组合开发上下文，不能替代模块边界，也不会自动把嵌套目录下的所有模块加入工作区。

用 go work init 和 use 建立本地共享版本

进入共同父目录执行下面的命令：

# 在仓库根目录创建工作区，并登记两个独立模块
go work init ./client ./shared

# 后续新增模块时，只追加含 go.mod 的目录
go work use ./tools

生成的 go.work 会包含 go 版本行和多个 use 路径。此后，从 repo 的工作区范围内运行 Go 命令，模块解析会把已登记的本地模块当作主模块；修改 shared 后，client 不需要等待一个新版本发布就能编译和测试。

用命令确认当前真的在 workspace 模式

“命令成功”不能证明用的是本地代码，先看工作区文件和模块目录：

# 输出当前 Go 命令实际采用的工作区文件；off 表示已关闭
go env GOWORK

# 在工作区根目录列出参与构建的模块
go list -m all

# 修改 shared 后，从工作区范围测试 client
go test ./client/...

如果 go env GOWORK 指向预期的 go.work，并且 go list -m all 中出现本地模块，才说明上下文对了。若结果仍来自模块缓存，先检查当前目录是否在 go.work 覆盖范围内、use 路径是否写到了真正含 go.mod 的目录，以及是否设置了 GOWORK=off。

模块目录很多时可以递归登记：

# 递归寻找参数目录中的 go.mod，并更新 use 列表
go work use -r .

这条命令方便，但也可能把实验模块、示例模块加入工作区；团队仓库更适合显式列出真正需要联调的目录。

go.work、replace 和 CI 的边界要分开

go.work 适合个人或团队的联调入口；replace 写进某个模块的 go.mod 则会影响这个模块被其他环境消费时的依赖声明。临时本地开发优先放在工作区，避免把开发机绝对路径提交进模块文件。

官方模块参考特别提醒：提交 go.work 可能让 CI 选择错误的依赖版本。因此 CI 可以显式关闭它，并在每个模块目录测试：

# CI 只按模块自己的 go.mod 解析依赖
GOWORK=off go test ./client/...
GOWORK=off go test ./shared/...

若团队决定提交 go.work，就应同时约定它的覆盖范围、更新责任和 CI 行为。需要把工作区构建列表中的依赖版本同步回各模块时再执行 go work sync，因为它可能改写多个 go.mod，不应当作为每次联调的无脑步骤。

常见问题

go.work 能自动包含子目录里的所有模块吗？

不能。use 的参数应直接指向模块目录；只有使用 go work use -r 才会递归寻找模块，而且仍要检查是否误收录了不相关目录。

本地共享版本是否需要给 shared 加 replace？

同一工作区内通常不需要。把 shared 加入 use 后，工作区会使用它的本地源码；离开工作区后，client 仍需依赖一个可获取的正式版本。

为什么 CI 里的测试和本地结果不同？

最常见原因是本地启用了 go.work 而 CI 没有，或者反过来。分别查看 go env GOWORK，并用 GOWORK=off 做一次模块级回归测试。