Go go.work 如何让多个模块共享本地依赖

两个 Go 模块需要一起开发时，最容易留下的临时痕迹就是 go.mod 里的本地 replace。更稳妥的做法是在两个模块的共同父目录创建 go.work，用 use 登记它们。这样，工作区内的构建可以直接读取本地模块；模块自身的依赖声明仍保持可发布状态。

一句话记忆：go.mod 描述单个模块如何被别人使用，go.work 描述你在本机如何同时开发多个模块。联调结束后，用 GOWORK=off 做一次单模块复查。

go.work 解决的是本地模块边界，不是发布版本

假设目录里有 web 和 shared 两个模块，web 依赖 example.com/shared。单独进入 web 时，Go 通常会按 web/go.mod 中的版本解析；进入 workspace 后，两个模块都成为本地工作区的主模块，导入路径仍然必须与 shared/go.mod 的 module 行一致。

在共同父目录创建 go.work 并登记模块

把工作区根目录放在两个模块的共同父目录，例如 workspace/。首次创建可以直接传入模块目录；后续新增模块用 go work use。这些命令只修改工作区文件，不会把本地路径写进 web/go.mod。

# 在两个模块的共同父目录操作，路径相对 go.work 文件
cd workspace

# 创建工作区，并登记两个包含 go.mod 的本地模块
go work init ./web ./shared

# 查看 Go 命令当前实际使用的 go.work；为空表示未启用工作区
go env GOWORK

# 后续新增一个模块；需要递归发现子目录模块时再使用 -r
go work use ./contracts
# go work use -r ./modules

生成后的文件核心部分类似 use ( ./web ./shared )。use 的路径指向模块根目录，而不是某个 Go 源文件；如果目录没有 go.mod 或路径已经不存在，登记就会失败或被移除。路径确认后，再从 workspace 根目录执行面向模块的命令。

让 web 直接吃到 shared 的本地改动

shared/go.mod 中的模块名必须是 example.com/shared，web 的 Go 代码再按同一个导入路径引用。工作区解决的是“这个模块现在从哪里取”的本地开发问题，不会改变导入路径，也不应该要求你把 replace ... => ../shared 固化到 web/go.mod。

package main

import (
	"fmt"

	"example.com/shared/greeting"
)

func main() {
	// 这里按 shared 的 module path 导入，workspace 决定本地解析来源。
	fmt.Println(greeting.Text("Go"))
}

当 shared 的接口或实现发生变化时，可以在工作区内重新执行构建或测试，检查 web 看到的就是本地版本。若命令突然找不到包，先检查三件事：两个模块是否都在 use 中、导入路径是否与 module 完全一致、当前目录的上级路径是否真的能找到该 go.work。

发布前关闭 workspace，避免本地成功掩盖依赖问题

工作区适合开发，但官方文档提醒，提交 go.work 可能让 CI 选到错误的依赖版本。发布前建议把“本地联调”和“模块作为外部依赖被使用”分开检查：

# 确认当前是否落在某个 go.work 的影响范围内
go env GOWORK

# 关闭 workspace，在 web 模块自己的依赖声明下测试
GOWORK=off go test ./...

# 观察 go work sync 或其他命令是否改写了模块依赖
git diff -- go.mod go.sum go.work go.work.sum

Shell 环境变量名区分大小写，实际命令应写成 GOWORK=off。若希望把 workspace 构建列表中的依赖版本同步回各模块，才使用 go work sync，并仔细审阅每个 go.mod 的差异。多数项目不应为了本地联调提交 go.work；只有模块长期只在同一仓库内协同开发、且团队明确接受该约束时，才考虑纳入版本控制。

常见问题

go.work 会自动修改 go.mod 吗？

仅创建或使用 workspace 不等于自动写入本地 replace。但 go work sync 会把 workspace 构建列表中的依赖版本同步回工作区模块，运行前应准备好审阅差异。

为什么已经有 go.work，命令仍然下载远程版本？

通常是模块未被 use 登记，或导入路径与模块的 module 声明不一致。先用 go env GOWORK 找到实际文件，再检查路径和模块名。

团队项目应该提交 go.work 吗？

默认不建议。它可能覆盖父目录工作区或影响 CI 的依赖选择；只有仓库明确把多个模块作为固定组合开发，并同时做好各模块独立测试和发布时，才适合提交。

最终可以把判断标准压缩成一句话：本地并行开发用 go.work，模块对外发布靠各自的 go.mod；任何只在本机成立的路径，都要在 GOWORK=off 的复查中重新面对。