Go workspace 管理多模块本地联调

多个 Go 模块同时开发时，最稳妥的联调方式是把模块目录放进同一个 workspace，用 go.work 管理本地解析；发布前再用 GOWORK=off 脱离本地目录做一次独立检查。这样既不用把临时 replace 写进模块，也能尽早发现“本机能编译、干净环境不能编译”的问题。

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

一、先把 workspace 根目录和模块边界定清楚

假设目录中有一个业务模块 service 和一个共享模块 shared。两者各自拥有 go.mod，workspace 根目录只负责描述本地开发关系，不替代模块本身的依赖声明。建议把 go.work 放在两个模块的共同父目录，并使用稳定的相对路径。

这一步的关键不是把所有目录都塞进去，而是确认每个 use 目录确实包含 go.mod，且模块路径与业务代码中的 import 一致。路径层级一旦混乱，后面的错误常常会被误判成版本冲突。

二、用 go work init 和 use 建立本地联调

在 workspace 根目录执行初始化和加入模块：

# 在共同父目录创建 workspace 文件
go work init ./service ./shared

# 后续新增模块时，只扩展本地 use 列表
go work use ./service ./shared

# 确认当前 Go 命令加载的 workspace 路径
go env GOWORK

# 查看当前解析到的模块与版本
go list -m

go work init 会生成 go.work，go work use 负责追加或整理模块目录。重复执行时要留意当前工作目录：相对路径是相对于 go.work 解释的，移动文件夹后不要只修 import 而忘了修 workspace。

三、在 workspace 作用域内测试和同步依赖

建立关系后，在 workspace 根目录运行测试，才能覆盖多个模块：

# 运行 workspace 作用域内的全部包测试
go test ./...

# 当 go.mod 需要补齐 workspace 中可见的模块版本时再同步
go work sync

# 单独查看某个模块的依赖图，便于区分解析问题和测试失败
go list -m all

go test ./... 失败时先看失败模块和第一条错误，不要立即重复执行 go work sync。同步会改写模块依赖文件，适合解决明确的依赖一致性问题，不是所有编译错误的通用修复。若只是共享模块代码未更新，先确认业务模块 import 的模块路径和本地目录是否对应。

四、发布前用 GOWORK=off 做一次独立校验

workspace 解决的是本地开发体验，不能自动证明发布环境也能解析这些模块。准备提交或构建时，至少对目标模块做一次关闭 workspace 的检查：

# 关闭 go.work，检查模块是否能独立解析依赖
GOWORK=off go list -m all

# 在不使用本地 workspace 的条件下运行目标模块测试
GOWORK=off go test ./service/...

# 只在明确需要共享 workspace 的团队流程中提交 go.work
git diff -- go.work service/go.mod shared/go.mod

如果关闭 workspace 后失败，通常意味着依赖模块还没有发布到可解析的位置，或者模块的 go.mod 仍依赖本地 replace。此时应先决定模块是一起发布、使用版本号，还是在 CI 中显式准备多模块源码；不要把开发机绝对路径提交进去。

相关问题

go.work 能替代 go.mod 吗？

不能。go.mod 描述单个模块的依赖和模块路径，go.work 主要组合多个本地模块的开发作用域。

本地联调为什么能过，独立测试却失败？

常见原因是 workspace 让 Go 找到了本地模块，而独立测试只能按模块声明、代理或版本库来源解析依赖。用 GOWORK=off 可以把这层差异显式暴露出来。

每次修改共享模块都要执行 go work sync 吗？

不需要。普通源码修改先运行测试即可；只有需要把 workspace 中的模块版本关系同步回模块文件时，才执行 go work sync，并审阅产生的 diff。