Go 1.11+ 多模块项目需为每个子模块单独创建 go.mod 文件并显式声明依赖，不可依赖顶层模块管理；本地开发用 replace，CI 用 go mod edit -replace，发布前须移除 replace 并使用真实版本号。
Go 1.11+ 多模块项目必须用 go.mod 文件逐个声明
Go 没有“工作区”或“父级模块”的概念，每个目录下只要执行过 go mod init，就成为一个独立模块。多模块项目不是靠一个顶层 go.mod 管理所有子模块，而是每个子模块都应有自己完整的 go.mod，并显式声明对其他本地模块的依赖。
常见错误是把多个服务目录放在同一仓库但只在根目录初始化模块，结果子目录里 go build 报错：cannot find module providing package xxx —— 因为 Go 不会自动向上查找模块边界。
- 每个服务/库目录运行
go mod init example.com/project/api（模块路径需唯一且可解析） - 若
api依赖同仓库的shared，在api/go.mod中写：require example.com/project/shared v0.0.0<br>replace example.com/project/shared => ../shared
-
replace是开发期必需的，否则 Go 会尝试从 proxy 下载v0.0.0（根本不存在）
replace 和 go mod edit -replace 的区别与适用场景
replace 直接写在 go.mod 里，适用于长期本地联调；go mod edit -replace 是命令行临时覆盖，适合 CI 或单次构建，不污染代码。
容易踩的坑：在 go.mod 里写了 replace，却忘了在 CI 脚本中用 go mod tidy + go build，导致构建时仍走 proxy，报 missing go.sum entry。
立即学习“go语言免费学习笔记（深入）”；
- 开发时：直接编辑
go.mod加replace，再运行go mod tidy同步go.sum - CI 构建时：用
go mod edit -replace example.com/project/shared=../shared，再go mod tidy，避免提交临时修改 - 发布前务必删掉
replace行，并用真实版本号（如v0.1.0）更新require
跨模块测试时 go test 找不到依赖包
在模块 A 中运行 go test ./... 时，如果测试代码 import 了模块 B 的包，而模块 B 未被正确 require 或 replace，就会报 import "example.com/project/b": cannot find module。
这不是路径问题，是模块加载顺序问题：Go 只加载当前目录所在模块及其 required 的模块，不会自动扫描兄弟目录。
- 确保模块 A 的
go.mod中已require模块 B，并配replace - 不要在模块 A 根目录外执行
go test；也不要 cd 进子目录再 test —— 必须在模块 A 的go.mod所在目录下运行 - 如果测试需要同时启动 A 和 B（比如集成测试），建议写 shell 脚本分别
go run两个模块，而不是试图在一个go test进程里 import 两者
发布多模块项目时 go install 和 go build 行为差异
go install 默认只安装当前模块的 main 包，且要求 GOPATH/bin 或 GOBIN 在 $PATH 中；go build 则生成二进制到当前目录。多模块项目常误以为 go install ./... 能批量安装所有 main 包，实际会失败。
真正可靠的做法是明确指定每个 main 包路径：
- 模块
cmd/api：运行go install example.com/project/api/cmd/api@latest - 模块
cmd/worker：运行go install example.com/project/worker/cmd/worker@latest - 注意：必须用完整模块路径 +
@latest（或具体版本），不能用相对路径./cmd/api - 若尚未打 tag，
@latest会 fallback 到main分支的 latest commit，但需确保该 commit 已go mod tidy并提交go.sum
模块路径拼写错误、忘记 @latest、或 go.sum 未提交，都会让 go install 静默失败或拉取旧版本。
