Go Modules在多模块项目中易出错，因默认仅支持单go.mod管理，子目录随意init会导致主模块无法识别、replace失效；根本原因是模块解析仅向上查找最近go.mod，子模块需显式require或replace才能被承认。
Go Modules 为什么在多模块项目里容易出错
Go 1.11 引入的 go mod 默认只支持单个 go.mod 文件管理整个项目，但真实业务中常有多个子模块（如 api/、service/、shared/）需要独立版本控制或不同依赖策略。直接在每个子目录下 go mod init 会导致主模块无法识别子模块，go build 报 no required module provides package，或者 replace 失效。
根本原因在于 Go 的模块解析机制：它从当前工作目录向上查找最近的 go.mod，并以此为“主模块”；子目录若也有 go.mod，除非显式声明为独立模块（且被主模块 require），否则会被忽略。
- 不要在子目录随意
go mod init，除非你明确要发布该子模块为独立可导入包 - 如果子模块仅供内部复用（如
shared/utils），应保留在主模块内，不单独建go.mod - 若必须多模块（例如微服务拆分），需用
replace或require显式链接本地路径，且所有模块的module路径不能重复或冲突
如何让主模块正确引用本地子模块
典型场景：主项目 github.com/org/project 下有 shared/ 目录，你想在 api/ 中 import "github.com/org/project/shared"，但又不想发布 shared 到远程仓库。
关键不是改 import 路径，而是让主模块“承认”这个路径属于它自己——通过 replace 将模块路径映射到本地相对路径：
立即学习“go语言免费学习笔记（深入）”；
go mod edit -replace github.com/org/project/shared=./shared
执行后，go.mod 会新增一行：
时隔大半年了，在这个特殊的日子里，2013年7月8号，HTShop普及版1.0终于和大家见面了，久等了 (*^__^*) 嘻嘻…… 此次版本改进，修复了自上个版本发布以来发现的所有bug。还增加了更多的商务功能。不变的，依然是免费使用！ 介绍 以下说明适用于 HTShop 普及版 v1.0 HTShop普及版是一款可以免费下载使用，功能无任何限制的网店系统，内置SEO优化，具有模块丰富、管理简洁直
replace github.com/org/project/shared => ./shared
-
replace必须写在主模块的go.mod中，子模块自己的go.mod无效 - 路径必须是相对于主模块根目录的相对路径，不能用
../跨出项目根 - 被
replace的模块路径（左边）必须与代码中import的路径完全一致，包括大小写和斜杠方向 - 运行
go mod tidy后，go.sum才会包含该子模块的校验和
多模块项目中 go.sum 和缓存的陷阱
当使用 replace 指向本地子模块时，go build 不会从远程拉取该模块，但 go.sum 仍会记录其哈希值。一旦你误删 go.sum 或切换分支导致子模块内容变化，go build 可能静默失败或报 checksum mismatch，尤其在 CI 环境中。
- CI 构建前务必运行
go mod tidy -v，观察是否触发了子模块的 checksum 重计算 - 避免在
replace后手动修改go.sum；应让go mod tidy自动更新 - 如果子模块频繁变更，考虑用
go mod vendor锁定全部依赖（含本地替换），但注意 vendor 不会自动同步replace的路径变更 -
go list -m all可查看当前解析出的所有模块及其来源（(replaced)表示被replace了）
什么时候该用多模块，什么时候该忍着用单模块
多模块不是银弹。Go 官方推荐“一个仓库一个模块”，除非满足以下至少一项：
- 子模块需被其他外部项目独立
go get（如 SDK、CLI 工具） - 不同子模块生命周期差异极大（如前端构建工具和后端 API 服务，发布节奏完全不同）
- 团队按子模块划分，且各组对依赖升级有强自治权（例如安全补丁需独立灰度）
否则，硬拆多模块只会增加 replace 维护成本、CI 构建不确定性，以及新成员理解门槛。很多所谓“多模块需求”，其实用清晰的包结构（internal/、pkg/）、接口抽象和集成测试就能解决。
真正麻烦的从来不是怎么配置 go.mod，而是当某天有人把 replace 改成指向远程 tag，却忘了更新子模块的 go.mod 里 module 声明——这时候 import 路径就彻底断了。
