Go modules 怎样用 workspace 管理多模块

Go modules 管理多个本地模块，可以在共同父目录建立 go.work，用 use 列出参与开发的模块目录。它们会作为工作区中的主模块参与解析，应用能直接使用旁边尚未发布的库代码，不必为每次联调修改各模块的 replace。go.work 不合并 go.mod，也不替代库正式发布后的版本依赖。

设想一个应用 app 与一个小库 labelkit 同时开发：库接口刚改，应用还没升级正式依赖。这正是 workspace 适合解决的场景；但如果只在工作区里测试，很容易漏掉应用 go.mod 不完整的问题。官方地址：https://go.dev/doc/tutorial/workspaces；模块参考：https://go.dev/ref/mod#workspaces。

两个模块联调时，workspace 改变了什么

应用 import 的仍是库 go.mod 声明的模块路径，不是文件系统相对路径。go.work 中的 use 则填写本地模块目录，两者作用不同。将 app 和 labelkit 都加入工作区后，Go 可以从本地 labelkit 取源码，而无需先发布一个临时版本。

这种安排适合跨仓库联调，也适合同一仓库中确实需要独立版本管理的多个模块。若只是一个应用内部的几个普通包，通常保留一个 go.mod 更直接，没有必要为了目录多就拆成多个模块。

先确认工具链和工作区发现规则

Workspace 从 Go 1.18 开始支持。实际项目还要满足各模块以及 go.work 的 go 指令所要求的工具链；不要把“支持 go work”理解成任意旧工具链都能构建新版本源码。以下命令供读者执行，本文没有运行这些示例。

# 查看当前工具链和实际启用的工作区文件。
go version
go env GOWORK

默认情况下，go 命令会从当前目录逐级向父目录寻找 go.work，所以“我在模块目录里运行”并不代表工作区已经关闭。需要独立模块模式时，给单条命令设置 GOWORK=off。本文 shell 示例使用 POSIX 语法，PowerShell 等环境需要改用对应的环境变量赋值方式。

建立只有两个模块的最小示例

在一个空的演示父目录里创建 app 和 labelkit 两个目录。分别保存下面文件，不要覆盖已有项目。这里使用保留的 example 模块路径，只用于自包含示例，不能当作真实发布地址。

labelkit/go.mod：

// 独立库模块，示例选择最低 workspace 支持版本。
module example/labelkit

go 1.18

labelkit/label.go：

package labelkit

// Label 为演示项增加统一前缀，便于观察本地源码修改。
func Label(name string) string {
    return "item:" + name
}

app/go.mod：

// 演示应用保持独立模块身份；此处刻意没有正式库版本。
module example/app

go 1.18

app/main.go：

package main

import (
    "fmt"
    "example/labelkit"
)

// main 按模块路径导入库，而不是导入 ../labelkit。
func main() {
    fmt.Println(labelkit.Label("draft"))
}

回到共同父目录创建工作区，再显式指定两个模块内的包模式：

# 仅在尚无 go.work 的演示父目录初始化。
go work init ./app ./labelkit
# 查看本次自动生成的工作区文件位置。
go env GOWORK
# 显式覆盖两个模块，不把父目录误当作模块根。
go test ./app/... ./labelkit/...
go run ./app

预期运行输出是 item:draft；测试命令在没有测试文件时不会替你证明业务正确。本例未执行，输出只是基于代码的预期。修改库返回值后再次运行应用，应该能观察到本地修改。若没有变化，先检查 GOWORK 与 use 指向，而不是给 import 换成相对路径。

go work init 会按当前工具链写入相应版本信息，生成的 go.work 不一定与文章中某个固定版本号相同。已经存在 go.work 时，使用 go work use ./app ./labelkit 添加目录，不要再次初始化。

处理 replace 和依赖同步的边界

工作区内各主模块的 go.mod 都参与依赖解析。go.work 的 replace 可以覆盖模块里的相应 replace；不同主模块对同一依赖存在冲突替换时，需要统一安排，不能期望 Go 随机选择一个。加入 use 的目录也应保持正确的 module 声明，目录名相同并不能消除模块路径冲突。

本地跨模块开发优先用 use 表达哪些模块参与，而不是给每个 go.mod 填一串机器相关路径。对于工作区外的替换需求，才根据实际情况使用 go.work replace。它不会让下游用户自动获得你的本地目录，也不是依赖发布机制。

go work sync 不是只读命令，可能把工作区选择的依赖版本同步进各模块的 go.mod。应在需要统一依赖时明确执行，并阅读变更；它不等同于把所有模块合成一个 go.mod，也不是每次 go run 之前都要执行的准备动作。go mod tidy 仍应按模块处理，不要把它当成整个工作区的统一整理器。

发布前回到独立模块视角

上面的 app 没写 require，是有意展示 workspace 能掩盖的问题。真实应用独立构建前，应把库发布到可访问的真实模块路径，再在 app 中声明实际版本。本文不虚构一个可下载版本。若库尚未发布，只能明确采用受控的本地替换或整体工作区构建，不能宣称应用已经具备独立发布条件。

在每个模块目录分别检查，以下以 app 为例：

# 在 app 模块目录执行，不继承父目录工作区。
GOWORK=off go test ./...
# 依赖已指向真实可获取版本后，再检查独立构建。
GOWORK=off go build ./...

对本例刻意不完整的 app，关闭工作区后无法按原样解析旁边的库，这是应当发现的依赖缺口，不是 workspace 损坏。CI 可同时保留工作区联调任务和各模块独立任务，两者回答不同问题。

是否提交 go.work 取决于仓库约定：个人跨仓库组合通常不提交；团队共同维护的多模块仓库，可以明确约定并提交，但目录布局、CI 与工具链也必须一致。不要把个人绝对路径或仅自己存在的目录带给同事。go.work.sum 与各模块 go.sum 也不是同一个文件，不能随意互相替换。

常见问题与选择清单

为什么父目录的 go test ./... 不覆盖所有模块？

包模式从所在目录解释；没有 go.mod 的工作区父目录并非自动变成统一模块根。像本例这样显式列出 ./app/... 和 ./labelkit/...，意图更明确。

工具链不支持 workspace 怎么办？

优先使用满足项目要求的工具链。无法升级时，可以在兼容源码的前提下退回单模块开发及受控 replace，但它不是无成本替代方案，还需要管理本地路径和发布配置差异。

Workspace 会提高运行速度吗？

它解决的是开发期模块组合与解析，不应据此承诺服务运行更快。判断是否采用，看跨模块联调是否需要，而不是追求没有依据的性能收益。