c++20 的 private 模块分区是模块内的实现隔离机制，用 module : private 声明，仅限同一主模块的其他分区访问，对外部完全不可见，需同名、参与构建且注意编译顺序。
什么是 C++20 的 private 模块分区
它不是“私有模块”，而是模块（module）内部的一种**实现隔离机制**：用 module : private 声明的分区，其内容只能被同一主模块（module）的其他分区访问，对外部导入者完全不可见。本质是把实现细节“关进同一个模块的笼子”，而非靠命名约定或头文件隐藏。
常见错误现象：import mylib; 却意外能访问到本该隐藏的辅助函数或内部类；或者把实现写在主模块接口单元里，导致编译依赖爆炸、头文件污染。
- 必须和主模块同名（如主模块叫
mylib，分区就得写module mylib : private;） - 不能被其他模块
import，连export import都不行 - 主模块接口单元（
module mylib;）可通过import或直接声明引用该分区里的符号，但需确保分区已先编译
module : private 怎么写才不报错
最常踩的坑是路径与编译顺序——分区文件本身不生成独立接口，但必须参与构建，且顺序不能乱。Clang 和 MSVC 对此处理略有差异，GCC 13+ 才初步支持。
- 分区文件（如
mylib_private.cppm）里写：module mylib : private;<br>namespace detail { void helper(); } - 主模块接口单元（
mylib.cppm）里写：export module mylib;<br>import : private; // ← 注意冒号前无空格<br>export namespace mylib { void api(); } - 链接时必须把
mylib_private.cppm和mylib.cppm一起传给编译器，不能只编译后者 - MSVC 要求分区文件扩展名也用
.cppm；Clang 允许.ixx，但必须显式指定-x c++-system-header等标志
为什么不用 internal linkage 或 static 替代
因为它们解决的是不同层面的问题：static 或 inline 匿名命名空间只能限制**翻译单元内可见性**，而模块分区控制的是**模块边界内的符号可见性**——前者无法阻止头文件被多次包含后重复定义，后者天然避免 ODR 违规，且支持跨多个源文件的私有逻辑复用。
立即学习“C++免费学习笔记（深入）”；
- 用
static函数放头文件里 → 多次包含就多份副本，bloat 二进制 - 用
inline namespace detail→ 外部仍可通过mylib::detail::helper()访问，没真正隐藏 - 用
module : private→ 符号根本不出现在模块接口中，import mylib;后连名字都查不到 - 性能影响几乎为零：分区内容只参与主模块编译，不增加导出符号表大小
哪些场景下千万别用 private 分区
它不是万能封装锤。当你需要跨模块复用某组工具函数，或想做“半公开”API（比如供测试模块访问），private 分区反而会锁死架构演进。
- 测试需要调用内部函数？→ 改用
module mylib : test;（非标准，靠编译器扩展或宏模拟）或单独抽成mylib_test_support模块 - 多个模块共享同一套底层实现？→ 应该提取为独立的
mylib_core模块，再让其他模块import它 - 项目还没启用模块系统（混合
#include和模块）？→ 分区内容可能因预处理行为异常暴露，建议全量迁移完成后再引入 - 目标平台是嵌入式或老 GCC（detail/ 子目录更稳妥
模块分区的“私有”是编译期强约束，但它的价值高度依赖整个构建链路对模块语义的一致理解——一个环节掉链子，隐藏就变成幻觉。
