go.work 是 monorepo 的必要基础设施，因 Go 工具链默认只识别首个 go.mod，多模块需靠 go.work 统一管理依赖、支持跨模块开发测试；它须置于根目录，配合各子模块独立 go.mod，并通过 go work use 显式添加路径。
Go monorepo 项目里不能靠多个 go.mod 文件“自然共存”——Go 工具链默认只认当前目录向上找到的第一个 go.mod，其余模块若未被主模块显式依赖，就会被忽略或报 cannot find module providing package 错误。
为什么 go.work 是 monorepo 的必要基础设施
单靠 go mod edit -replace 或 replace 指令只能临时绕过路径问题，无法支持跨模块开发、测试和构建的一致性。真正可行的方案是启用 Go 1.18+ 引入的 go.work 文件，它让 Go 命令（go build、go test、go run）能同时感知多个模块，并统一解析依赖。
-
go.work必须位于 monorepo 根目录，且仅对当前工作区生效（不提交到 GOPROXY） - 每个子模块仍需保留自己的
go.mod（含正确module路径），否则go.work无法识别为有效模块 - 执行
go work init后，用go work use ./service/auth ./pkg/utils显式添加模块路径，不要写相对路径如../pkg/utils - 若某模块尚未初始化
go.mod，go work use会失败，需先在该目录下运行go mod init example.com/service/auth
如何避免 replace 和 indirect 依赖污染
在 go.work 环境下，replace 指令不再是必需项；滥用 replace 会导致 go list -m all 输出混乱，且 go mod tidy 可能意外降级间接依赖版本。
- 删除所有
replace行——go.work已确保本地模块优先被加载 - 子模块的
go.mod中应使用真实语义化版本（如v0.1.0）声明对其他本地模块的依赖，例如：require example.com/pkg/utils v0.1.0 - CI 构建时禁用
go.work（通过GOWORK=off环境变量），改用cd ./service/api && go build单模块构建，避免工作区状态干扰 - 本地开发时运行
go work sync可将go.work中各模块的依赖快照同步进各自go.mod，但仅用于调试，不应提交
go.work 与 IDE（如 VS Code + Go extension）的兼容要点
VS Code 的 Go 插件默认不自动识别 go.work，需手动启用或重启语言服务器。
- 确认已安装 Go 1.18+，并在 VS Code 设置中开启
"go.useLanguageServer": true - 打开 monorepo 根目录后，状态栏右下角应显示
Workspace: on，而非Module: xxx；若未生效，执行命令面板中的Go: Restart Language Server - 部分老版本插件会忽略
go.work中未被主模块直接 import 的包，此时需在任意.go文件中临时加一行_ "example.com/pkg/xxx"触发索引 - GoLand 用户需在
Settings > Go > Modules中勾选Enable Go Workspaces
go.work use ( ./cmd/cli ./service/user ./service/order ./pkg/database ./pkg/logging )
真正麻烦的不是配置 go.work，而是当某个子模块升级了依赖版本，却忘了同步更新其他模块的 go.mod 中对应 require 行的版本号——这种不一致在 go.work 下不会报错，但会破坏可重现构建。
