为单仓多模块项目设计不提交个人路径的工作区流程

单仓多模块项目最稳妥的做法，是把“可提交的模块契约”和“开发者本地工作区”拆成两层：每个模块的 go.mod、go.sum 以及工作区初始化脚本进入版本库；根目录的 go.work、go.work.sum 由开发者按需生成并加入忽略列表。这样既能本地联调多个模块，又不会提交用户名、磁盘盘符、主目录或个人选择的模块集合。

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

把仓库契约与个人工作区分成两层

go.work 的 use 指令会把磁盘上的模块目录加入工作区。它非常适合同时修改 API 服务和共享库，但也会改变依赖选择。Go 官方模块参考通常不建议把个人工作区文件提交进版本库：一方面，它可能覆盖开发者从父目录继承的工作区；另一方面，CI 可能因此测试到本地模块组合，而不是模块作为外部依赖时的真实状态。

可以先定义一条简单边界：

用根目录锚定的忽略规则挡住本地文件

在仓库根目录的 .gitignore 中加入以下规则。开头的斜杠把范围限定在仓库根目录，不会误伤子目录中用于测试或示例的同名文件：

# Go 多模块工作区只在本地生成，不提交个人模块组合
/go.work
/go.work.sum

不要用忽略规则掩盖模块自身的 go.mod 或 go.sum。工作区只是开发辅助层；真正决定模块能否被别人构建的，仍是模块目录中的依赖声明。

只用仓库相对路径生成 go.work

假设仓库结构如下，API 服务依赖共享库，同时还有一个可选的命令行工具：

repo/
├── .gitignore
├── scripts/
│   └── workspace-init.sh
├── services/
│   └── api/
│       └── go.mod
├── libs/
│   └── shared/
│       └── go.mod
└── tools/
    └── migrate/
        └── go.mod

最小、可预测的工作区使用显式模块清单：

# 必须从仓库根目录执行，生成只含相对路径的本地工作区
go work init ./services/api ./libs/shared

# 查看当前 Go 命令使用的工作区文件，确认没有指向个人目录
go env GOWORK

# 输出规范化后的 use 列表，便于检查模块集合
go work edit -json

生成的文件类似下面这样。路径都相对于 go.work 所在目录，因此不会出现 /Users/alice、C:\Users\bob 或某块个人磁盘：

go 1.22

use (
    ./libs/shared  // 仓库内共享模块
    ./services/api // 仓库内 API 模块
)

当仓库模块很多、目录结构稳定时，可以用 go work use -r 递归发现包含 go.mod 的目录；不过它会把搜索范围内的所有模块纳入工作区。核心服务仓库通常更适合显式清单，工具集合仓库才适合递归发现。

把初始化封装成可重复执行脚本

不要让每个成员在文档里复制多条命令。提交一个脚本，并让脚本根据自身位置计算仓库根目录，而不是写死某个人的绝对路径：

#!/usr/bin/env sh
set -eu

# 由脚本文件位置计算仓库根目录，与当前用户名和启动目录无关
repo_root=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
cd "$repo_root"

# 删除旧的本地工作区结果，保证重复执行得到同一模块集合
rm -f go.work go.work.sum

# 使用仓库相对目录生成最小工作区
go work init ./services/api ./libs/shared

# 可选工具模块单独加入，仍保持相对路径
go work use ./tools/migrate

# 规范化文件，便于本地检查
go work edit -fmt

# 打印实际工作区位置，让调用者确认已经启用
go env GOWORK

脚本的输入是“仓库结构”，输出是“本地工作区”。它可以反复运行：新增模块后只改脚本中的相对清单，团队成员重建即可。因为生成结果已经忽略，分支切换时也不会出现无意义的 go.work 冲突。

需要个人模块组合时，使用本地增量

有人只改 API 和共享库，有人还要联调迁移工具。公共脚本可生成团队最小集合，个人再在本地增量添加或移除：

# 把当前开发者需要的工具模块加入本地工作区
go work use ./tools/migrate

# 不再需要时从本地工作区移除，不影响版本库
go work edit -dropuse=./tools/migrate

# 只格式化本地 go.work，不改各模块 go.mod
go work edit -fmt

这比提交一个包含所有目录的巨大 go.work 更清晰：共同部分由初始化脚本描述，个人选择由本地文件承载。若模块目录已经删除，go work use 也会根据不存在的参数路径移除对应 use。

本地联调与 CI 独立验证要分开

本地工作区让多个模块同时成为主模块，适合跨模块修改；CI 则应检查每个模块是否能够只靠自己的 go.mod 解析。GOWORK=off 是官方定义的单模块模式开关。

本地可以先做一次对照检查：

# 工作区模式下测试跨模块联调结果
go test ./...

# 进入 API 模块并关闭工作区，模拟独立消费者和发布环境
cd services/api
GOWORK=off go test ./...

# 再验证共享库自己的模块契约
cd ../../libs/shared
GOWORK=off go test ./...

如果第一组成功、第二组失败，优先检查 services/api/go.mod 是否缺少对 shared 模块的可获取版本要求。不要把“在 go.work 下能编译”当作模块依赖已经完整。

CI 用模块矩阵防止 go.work 遮住缺口

下面的 YAML 片段表达核心边界，不依赖某个具体 CI 品牌：矩阵列出可发布模块，测试进程统一关闭 workspace。

strategy:
  matrix:
    # 每个目录都必须包含独立有效的 go.mod
    module:
      - services/api
      - libs/shared
      - tools/migrate

steps:
  - name: Test each Go module independently
    working-directory: ${{ matrix.module }}
    env:
      # 禁止 CI 读取仓库根目录或父目录中的 go.work
      GOWORK: "off"
    run: go test ./...

如需额外的仓库级集成测试，可以再建一个明确启用本地工作区的 job，但不要用它替代模块矩阵。两者回答的问题不同：集成测试确认“这些本地模块能否一起工作”，单模块测试确认“每个模块能否独立被解析”。

怎样处理 go work sync

go work sync 会根据工作区的统一构建列表，把相关依赖版本同步回各 use 模块的 go.mod。它会修改被跟踪的模块文件，因此不应悄悄塞进每次初始化脚本。更合适的用法是：开发者明确希望对齐多个模块的外部依赖版本时手动执行，随后审查并提交模块文件变化。

# 明确需要统一外部依赖版本时才同步；执行后应审查 go.mod 差异
go work sync

# 查看被同步修改的模块文件，避免把无关版本升级混入提交
git diff -- '*/go.mod' '*/go.sum' '*/*/go.mod' '*/*/go.sum'

go work sync 不能把尚未发布的本地模块变成外部可下载版本，也不能替代单模块测试。它解决的是工作区构建列表与模块要求的版本对齐。

例外：什么时候可以提交 go.work

如果仓库内的模块永远只作为一个整体开发，从不被外部仓库单独引用，并且团队明确希望所有工具和 CI 使用同一个模块组合，那么提交 go.work 可能是合理例外。即便如此，也应满足三点：

• 所有 use 都是仓库相对路径，绝不出现个人绝对路径。
• CI 清楚区分 workspace 集成测试和 GOWORK=off 单模块测试。
• 每个可能发布的模块仍维护完整 go.mod，不把 workspace 当依赖声明。

也就是说，“提交或不提交”不是宗教问题，关键是不要让工作区隐式改变模块契约。本文方案偏向可拆分、可发布的单仓多模块项目，因此默认忽略个人 go.work。

常见问题

go.work.sum 也必须忽略吗？

如果 go.work 本身是本地生成的，配套的 go.work.sum 也应留在本地。各模块可重复构建需要的校验和应进入各自 go.sum，CI 的单模块测试会检查这一点。

为什么不用绝对路径避免目录层级变化？

绝对路径把工作区绑定到用户名、操作系统和磁盘布局，最难共享。初始化脚本应从自身位置定位仓库根目录，再让 Go 写入仓库相对 use 路径；目录调整时只改一处脚本清单。

可以只提交 go.work.example 吗？

可以，但示例文件还需要人工复制和维护，且 Go 命令不会自动读取它。可执行初始化脚本能直接生成格式正确的 go.work，更适合模块数量会变化的仓库；也可以在 README 中同时提供模块清单说明。

最终的职责分配很简单：go.mod 与 go.sum 负责模块自描述，初始化脚本负责把仓库结构转成个人工作区，.gitignore 阻止本地结果进入版本库，CI 的 GOWORK=off 负责证明每个模块没有借工作区“隐身”。四层边界都在，单仓多模块联调就能方便而不污染团队环境。