go.work 应不应该提交到仓库，团队协作边界如何定

go.work 的默认策略应是不提交到仓库。只有当仓库内的多个模块专门共同开发、use 集合长期稳定，并且 CI 仍会关闭工作区逐模块验证时，才适合把它作为共享仓库契约提交。判断重点不是“提交后能不能编译”，而是它会不会遮蔽真实依赖、覆盖开发者自己的工作区，或让 CI 测到错误的模块版本。

官方参考：https://go.dev/ref/mod#workspaces

可独立被外部项目引用的模块，优先忽略 go.work；只在仓库内部共同演进的紧耦合模块，可以提交，但必须保留 GOWORK=off 的发布测试。

官方为什么默认不建议提交 go.work

Go 模块参考给出两个明确原因。第一，仓库里的 go.work 可能覆盖开发者在父目录维护的个人工作区，使其原有 use 组合失效或产生困惑。第二，CI 可能因为工作区选择了本地模块和不同依赖版本，测试的并不是模块被外部项目 require 时的真实状态。

这意味着 go.work 更像“当前目录树的开发视图”，而 go.mod 才是模块对消费者公开的依赖契约。把开发视图提交并非语法错误，但会把一组本应可变的本地选择升级为全团队默认值，所以必须有清晰的仓库边界。

用四个问题决定是否提交

不要根据模块数量机械判断。两个模块也可能需要忽略，十个模块也可能适合提交。团队可以逐项回答下面四个问题。

只要“外部消费者”和“独立发布”占主导，就应倾向忽略。因为开发者在工作区里看到的是本地源码组合，外部消费者看到的是模块代理或版本库里的已发布版本，两者不是同一套依赖视图。

不提交时，团队如何保持开箱即用

忽略 go.work 不等于让每个人猜目录。可以在仓库文档中保存一条创建命令，让开发者在克隆后生成自己的工作区。工作区文件和补充校验和文件一起加入忽略规则：

# 个人工作区不进入版本控制
go.work
go.work.sum

上面是 .gitignore 内容；该格式没有注释语法限制问题，井号注释合法。开发者按需要创建：

# 在仓库根目录创建个人工作区，并纳入两个模块
go work init ./module-a ./module-b

# 检查当前命令实际使用的工作区路径
go env GOWORK

如果不同成员需要不同模块组合，这种方式最自然。个人可以额外 go work use ../shared-tools，不会把仓库外相对路径带给其他成员，也不会在代码评审中反复增删 use。

提交时，go.work 应满足哪些约束

紧耦合单仓可以提交，但文件内容应只表达仓库级事实。use 使用仓库内稳定相对路径，不引用个人主目录、相邻私有仓库或临时生成目录；工作区级 replace 只用于所有成员都认可的统一替换，不承载个人调试。

// 共享工作区只列出仓库内稳定模块
go 1.23.0

use (
    ./module-a
    ./module-b
)

如果提交 go.work，建议把 go.work.sum 采用同一策略：它记录工作区使用而各模块 go.sum 未集体覆盖的校验和。共享工作区需要可复现时一并提交；个人工作区被忽略时，go.work.sum 也一并忽略。这里是团队版本控制策略，不改变每个模块继续维护自己 go.sum 的责任。

CI 必须同时守住集成与发布边界

提交 go.work 最大的风险，是工作区测试通过后给出“模块可发布”的错觉。本地 module-a 可能包含尚未发布的接口，module-b 在工作区中可以调用它；但外部消费者只会下载 module-b/go.mod 指定的已发布版本。

因此 CI 至少要有两类检查：工作区通道验证多个模块的当前源码能否协同；单模块通道使用 GOWORK=off，验证每个模块离开工作区后是否仍可整理依赖、编译和测试。

# 工作区通道：验证仓库内模块的当前源码组合
go test ./module-a/... ./module-b/...

# 发布通道：关闭工作区，分别验证模块公开的依赖契约
(cd module-a && GOWORK=off go test ./...)
(cd module-b && GOWORK=off go test ./...)

发布通道失败而工作区通道成功，通常说明某个模块使用了另一个模块尚未发布的变更。处理方式是先发布被依赖模块，再在依赖方更新真实版本；不要通过放宽 CI 或继续依赖工作区掩盖问题。

go work sync 为什么要限制权限

go work sync 会计算工作区构建列表，并把相关的较高依赖版本写回各个 use 模块的 go.mod。它不是单纯格式化 go.work，也不是日常联调的必要命令。共享工作区越大，一次 sync 可能影响的模块文件越多。

团队可以约定：普通开发者可以修改 use，但 sync 产生的跨模块依赖升级必须由模块负责人审查；任何工作区级 replace 都要说明生命周期；包含本地绝对路径的变更不得合并。这样可以避免工作区从“协作入口”演变为隐性的集中依赖管理器。

一份可直接采用的团队边界模板

常见问题

仓库里已经提交 go.work，是否必须删除？

不必机械删除。先看它是否代表所有成员稳定共享的模块组合，再检查 CI 是否有关闭工作区的逐模块测试。若只是某位开发者的临时组合，改为忽略更合适。

为什么我在子目录运行命令仍然用了 go.work？

当 GOWORK 为空时，Go 会从当前目录向父目录查找 go.work。用 go env GOWORK 查看实际路径；需要单模块模式时显式设置 GOWORK=off。

提交 go.work 后能否只保留工作区测试？

不能。如果模块会独立发布或被外部引用，工作区测试无法证明已发布依赖组合可用。至少保留每个模块的单模块测试。

所有模块都在一个仓库，是否一定应该提交？

不一定。单仓只说明物理位置相同，不代表消费者、发布节奏和本地组合相同。只有共享组合确实是仓库契约时，提交才有稳定价值。