go monorepo 必须用 go.work 协调多模块，子模块 module 路径需全局唯一且带语义化版本后缀（如 /v2），禁用 vendor，严格避免本地路径误解析。
Go mod tidy 会错误拉取主模块外的本地路径
在 monorepo 中，多个 go.mod 并存时，go mod tidy 可能误将其他子模块的本地路径（如 ./service/user）当作远程依赖去解析，尤其当该路径未被当前模块的 replace 或 require 显式约束时。根本原因是 Go 的模块加载器默认按 import 路径查找模块，而未强制要求路径与模块名一致。
实操建议：
- 每个子模块的
go.mod文件中，module声明必须是**全局唯一且可解析的路径**（例如example.com/repo/service/user），不能用相对路径或./开头 - 主模块（通常是根目录）的
go.mod中，对所有子模块显式添加replace，例如：replace example.com/repo/service/user => ./service/user - 运行
go mod tidy前，确保当前工作目录是目标子模块所在目录，而非根目录——否则 Go 会尝试解析整个 repo 的 import 图，容易触发跨模块误引用
go.work 文件是 monorepo 的必需协调层
go.work 不是可选补充，而是 Go 1.18+ monorepo 的事实标准入口。它让 Go 工具链知道“哪些模块应被视作同一开发单元”，从而绕过 replace 的重复声明和 go mod edit -replace 的手动维护成本。
常见错误现象：不启用 go.work，仅靠 replace，会导致 go list -m all 输出混乱、ide（如 vs code + gopls）无法正确跳转、go run 执行时模块版本冲突。
立即学习“go语言免费学习笔记（深入）”；
实操建议：
- 在 repo 根目录创建
go.work，内容示例：go 1.22 use ( ./cmd/api ./service/user ./pkg/util ) - 所有子模块仍需保留独立
go.mod；go.work只协调加载，不替代模块定义 - 禁用
GO111MODULE=off，且不要在子目录下执行go work init—— 它只应在根目录初始化一次
vendor 目录在 monorepo 中基本失效
monorepo 下启用 go mod vendor 会产生不可靠结果：它只会为当前模块 vendoring，不会递归处理 go.work 中其他模块的依赖，更不会合并重复依赖。最终导致各子模块的 vendor/ 内容不一致，CI 构建行为与本地不一致。
性能与兼容性影响：vendor 同时增大 git 体积、拖慢 CI 拉取，并使 gopls 索引变慢。Go 官方已明确表示 vendor 是“legacy fallback”，非 monorepo 推荐路径。
实操建议：
- 全 repo 统一禁用 vendor：在根目录和所有子模块的
.gitignore中加入/vendor，并移除现有vendor/ - CI 中使用
go build -mod=readonly防止意外修改go.sum，而非依赖 vendor - 若因离线环境必须 vendor，请改用
go mod vendor+ 自定义脚本遍历go.work use列表中的每个目录分别执行，但需自行保证依赖版本对齐
发布子模块时 module path 必须带语义化版本后缀
monorepo 中单个子模块（如 example.com/repo/service/user）对外发布时，其 go.mod 的 module 行不能是 example.com/repo/service/user，而必须是 example.com/repo/service/user/v2（如果 v2 是当前大版本）。否则下游用户 go get example.com/repo/service/user@v2.1.0 会失败，因为 Go 不识别无版本后缀的模块路径的语义化版本。
关键细节：这个后缀不是 tag 名称，而是模块路径本身的一部分。tag 仍可打为 v2.1.0，但模块路径必须匹配。
实操建议：
- 发布前检查：
go list -m -f '{{.Path}} {{.Version}}' example.com/repo/service/user/v2应返回有效结果 - 避免在
go.work中直接 use 带版本后缀的路径（如./service/user/v2）——这会让本地开发路径与发布路径不一致；正确做法是本地仍用无版本路径，发布时仅修改go.mod中的module行并打 tag - CI 发布流程中，用
sed -i '' 's|module example.com/repo/service/user|module example.com/repo/service/user/v2|' service/user/go.mod（macOS）或sed -i 's|...|...|' ...（linux）动态注入版本后缀
实际落地时最易被忽略的是 go.work 和子模块 module 路径的协同粒度：一个字母错、一个斜杠少，就足以让 gopls 失效或 go test 找不到包。与其后期调试，不如在第一个子模块初始化时就固化命名规范。