Go通过go.work、replace、路径隔离和internal机制支撑Monorepo多模块协作，关键在于规范组织：go.work显式use子目录，replace需路径与module严格匹配，子模块独立发布依赖tag与go.mod一致性，internal提供路径级访问控制。
Go 本身不原生支持 Monorepo 的“子模块独立版本语义”，但通过 go.mod 分布、replace、go.work 和路径隔离，可以稳定支撑单体大仓库的多模块协作——关键不在“能不能”，而在“怎么组织才不翻车”。
go.work 是 Monorepo 多模块协同的起点，不是可选插件
当你在根目录下有多个带 go.mod 的子目录（如 ./api、./pkg/storage、./internal/tools），go.work 才是让它们“互相看见”的基础设施。没有它，go build 或 go test 默认只认当前目录的 go.mod，跨目录 import 就会报 cannot load xxx: module xxx not found。
实操建议：
-
go.work必须显式use每个含go.mod的子目录，路径不能重叠（例如不能同时use ./a和use ./a/b） -
use只接受目录，不支持通配符或模块名；子目录名不必和模块路径一致，但模块路径必须合法（如module github.com/org/repo/api） - CI 环境中，务必用绝对路径或
GOEXPERIMENT=aliases+go mod edit -replace注入依赖，避免相对路径失效 - 运行命令时，工作目录若不在
go.work的use列表内，Go 会自动退回到单模块模式——本地修改可能完全不生效
replace 不是万能胶，路径对齐错一步就构建失败
想在主模块里快速引用本地子模块？replace 最常用，也最容易出错。典型错误是：改了 replace 却没同步 require，或者子模块自己的 go.mod 里 module 声明和 import 路径不一致，导致 go build 静默跳过或报 unknown revision。
立即学习“go语言免费学习笔记（深入）”；
实操建议：
-
replace左边必须是代码里import实际写的路径（如github.com/org/repo/pkg/storage），右边是相对于当前go.mod的路径（如./pkg/storage）或file://绝对路径 - 被
replace的子模块，其自身go.mod中的module行必须与左边完全一致；不能写成./pkg/storage或空字符串 - 主模块的
go.mod中仍需require对应版本（哪怕只是v0.0.0-00010101000000-000000000000），否则go list -m all不显示，工具链可能忽略该依赖 - 子模块若有自己内部的
replace，不会自动继承到主模块——主模块要自己管好全部依赖上下文
子模块独立发布 ≠ Go 原生支持，靠的是路径+tag+手动维护
很多人误以为加了 go.work 或 replace 就能像 npm 那样自由发版。实际上，Go 没有“子模块版本注册中心”概念。所谓“github.com/org/repo/pkg/storage v1.2.3”，只是你把 tag 打在 pkg/storage 目录有变更的那个 commit 上，并确保该目录下 go.mod 的 module 是完整路径。
实操建议：
- 每个可独立发布的子模块，必须有自己的
go.mod，且module声明与导入路径严格一致 - tag 必须打在子模块目录有实质性变更的 commit 上，格式为
v1.2.3（不能是storage/v1.2.3或v1.2.3-storage） - 使用者执行
go get github.com/org/repo/pkg/storage@v1.2.3时，Go 会自动解析该子目录下的go.mod，而不是根目录的 - 在根目录执行
go list -m all看不到子模块版本——这是正常现象；要查子模块依赖树，得进到pkg/storage目录下单独执行
internal 包 + 目录边界 = Monorepo 里最便宜的访问控制
Monorepo 容易滑向“所有代码都能随便 import”的混乱状态。internal 不是语法糖，是 Go 编译器强制的访问限制机制：只有父目录及其同级目录下的代码，才能 import internal/xxx。这在单仓库多模块结构里，是最轻量、最可靠的模块封装手段。
实操建议：
- 把真正不该被外部（包括同仓库其他子模块）直接调用的实现细节，放进
internal/子目录（如pkg/storage/internal/codec） - 对外暴露的接口和类型，放在同级的非
internal包里（如pkg/storage/client.go） - 注意：
internal的限制基于文件系统路径，不是模块路径；即使两个模块分属不同go.mod，只要路径满足父子关系，限制依然生效 - 别指望
internal防止“同模块内滥用”——它只防跨路径，不防同包内胡来
Monorepo 在 Go 里真正难的不是技术拼装，而是模块边界的持续治理：谁有权改 go.mod、tag 谁来打、replace 何时切回 require、internal 的粒度怎么划——这些没法靠工具自动兜底，得靠团队共识和 CI 检查卡住。
