Go 1.11 多模块项目需用 replace 指令使主模块引用本地子模块，replace github.com/yourorg/lib => ./lib，发布前必须删除；import cycle 需抽离共享代码至独立模块；go.sum 要各模块独立维护并同步 tidy；私有仓库需配置 GOPRIVATE。
Go 1.11 引入的 go mod 默认只支持单模块（一个 go.mod 文件），多模块项目若直接套用，会遇到 cannot load ...: module ... is not a dependency of module ... 这类错误——根本原因不是“不支持”，而是 Go 的模块加载机制默认只识别当前目录向上最近的 go.mod，不会自动发现并链接同级或子目录下的其他模块。
多个 go.mod 文件共存时，如何让主模块正确引用本地子模块
关键在 replace 指令：它强制将某个模块路径映射到本地文件系统路径，绕过远程下载和版本解析。适用于开发阶段本地联调多个内部模块。
- 主模块（如
github.com/yourorg/app）的go.mod中添加：replace github.com/yourorg/lib => ./lib
-
./lib必须是完整模块目录，含自己的go.mod（module 声明为github.com/yourorg/lib） - 执行
go mod tidy后，go list -m all会显示github.com/yourorg/lib后缀带=> ./lib，表示已生效 - 注意：发布前必须删掉
replace，否则构建失败；CI 环境通常禁用 replace，需配合GOFLAGS="-mod=readonly"提前暴露问题
跨模块调用时出现 import cycle not allowed 怎么破
这不是 Go 模块问题，而是包导入结构缺陷：A 模块 import B，B 又间接或直接 import A。模块边界不能自动切断循环依赖。
- 检查
go list -f '{{.Deps}}' <pkg></pkg>或用go mod graph | grep找出实际引入链 - 常见诱因：共享常量/错误定义放在了被双向依赖的包里；应抽离到独立的
github.com/yourorg/shared模块，并在 A、B 中都replace它 - 避免在
internal/下跨模块放置共享代码——internal仅对本模块有效，其他模块无法 import
CI/CD 构建失败，提示 missing go.sum entry 或 checksum mismatch
根本原因是不同模块的 go.sum 不同步，尤其当子模块更新了依赖但主模块没运行 go mod tidy 时。
立即学习“go语言免费学习笔记（深入）”；
- 每个模块都应单独维护自己的
go.sum；不要删除子模块的go.sum，也不要把它们合并 - CI 构建主模块前，先
cd ./lib && go mod tidy && cd -，确保子模块依赖干净 - 使用
go mod verify在构建前校验所有模块的 checksum，比等go build报错更早发现问题 - 若子模块使用了私有 Git 仓库，需配置
GOPRIVATE=git.company.com/*，否则go mod download会尝试走 proxy 并失败
多模块项目的真正难点不在语法，而在于模块边界的语义一致性：每个 go.mod 不仅声明依赖，还定义了版本契约。一旦 replace 和 require 混用、或忘记清理临时替换，就容易在发布分支上触发静默错误——这些地方没有编译器报错，但 go list -m all 和 go mod graph 永远是最值得先跑的两个命令。
