Go项目Monorepo必须显式拆出多个go.mod并用go.work管理，否则无法实现模块独立版本、精准导入和按需构建；根目录单go.mod会导致所有子包被视作同一模块，破坏语义化版本与依赖隔离。
Go 项目构建 Monorepo 不是靠 go mod init 一次搞定的——它必须显式拆出多个 go.mod，并用 go.work 统一管理工作区，否则工具链无法识别模块边界，go run 和 go test 会直接报错找不到包。
为什么不能只在根目录放一个 go.mod
Go 的模块系统默认以 go.mod 所在目录为 module root，所有 import 路径都基于它解析。如果整个仓库只在根目录放一个 go.mod，那所有子目录的包都会被当成同一个 module 的一部分，导致：
- 无法为不同组件（如
cli、api、shared）设置独立版本号 - 发布时只能打一个 tag，无法支持
v1.2.0和v2.0.0并行迭代 -
go get引用时路径混乱，例如example.com/repo/cli和example.com/repo/api实际指向同一模块，语义错误 - CI 中无法按需构建单个模块，每次都要全量拉取和编译
必须手动创建多个 go.mod 并配置 go.work
每个逻辑上独立演进的模块（比如一个 CLI 工具、一个 HTTP 服务、一个通用工具库）都应在各自子目录下运行 go mod init，生成专属 go.mod。然后在仓库根目录创建 go.work 文件，显式列出所有模块路径：
go 1.21 use ( ./cli ./api ./shared )
关键点：
-
go.work是开发期文件，不参与发布，也不影响go build或go install行为 - 每个子模块的
go.mod中module字段必须唯一且带版本后缀（如example.com/repo/cli/v2），避免导入冲突 - 子模块之间依赖应通过完整模块路径引用（如
import "example.com/repo/shared"），而不是相对路径 - 执行
go work use ./cli可动态添加模块，但建议初始就写死在go.work中，避免 CI 环境遗漏
本地开发时 go run 报 no required module provides package
这是最常遇到的错误，根本原因是当前工作目录没激活 go.work，或者 go.work 没包含目标模块路径。验证方式：
- 运行
go work list，确认输出包含你要用的模块路径 - 确保你在仓库根目录（有
go.work的地方）执行go run ./cli/main.go，而不是进入./cli后再跑 - 如果仍失败，检查
go.work里路径是否拼错（比如写成./cmd/cli却实际是./cli） - 不要依赖
GO111MODULE=off回退到 GOPATH 模式——它会让所有模块解析失效
发布时怎么打 tag？每个模块单独打，且路径必须匹配 go.mod
Go 的 go get 机制靠 tag 名称匹配模块路径中的版本号。例如：
-
./shared/go.mod声明module example.com/repo/shared/v3→ 必须打 tagv3.1.0 -
./api/go.mod声明module example.com/repo/api/v2→ 对应 tagv2.5.0
切记：
- 不能全仓库统一打
v1.0.0—— 这会导致go get example.com/repo/shared@v1.0.0解析失败 - tag 必须推送到远程，且分支名无关（
main或develop都不影响go get） - 若模块路径含
/v2，tag 名必须含v2前缀，否则 Go 工具链拒绝识别为该版本
真正容易被忽略的是：模块路径、go.work 路径、git tag 名称这三者必须严格对齐，差一个字符或斜杠，go 命令就会静默失败或报错。调试时优先查这三项是否一致。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
