模块片段是c++20中用于隔离模块私有实现的机制，声明为module : private，不可被import，仅能被同一模块的主接口通过import : private;引入，用以隐藏辅助函数等内部细节、提升构建效率与ABI稳定性。
什么是 module partition（模块片段）？
模块片段是 C++20 中用于拆分模块接口与实现的机制，它本身不能被 import，只能被同一模块单元中的主模块接口（module Interface unit）引用。它的核心作用就是把不想暴露给用户的具体实现（如辅助函数、内部类、模板特化细节）抽离出去，避免污染模块接口。
关键点：模块片段不是独立模块，没有自己的 export module 声明；它用 module : private 或 module YourModuleName : private 声明，且必须和主模块在同一翻译单元或通过 #include-style 包含关系被主模块“拉入”。
如何声明和使用私有模块片段？
主模块接口文件（mathlib.ixx）负责导出用户可见的 API；私有片段（mathlib.impl.ixx）存放不对外公开的逻辑。二者需满足以下条件才能正确链接：
- 私有片段必须在主模块接口中被显式导入（用
import : private;），不能靠编译器自动发现 - 私有片段中不能出现
export关键字（否则编译器报错：export cannot appear in a private module fragment） - 私有片段可访问主模块接口中
export的符号，但反之不成立——主模块接口不能直接访问私有片段里的非导出名，除非已通过import : private;引入
// mathlib.ixx（主模块接口） export module mathlib; export int add(int a, int b); // 导入私有片段，使其内容对本模块可见 import : private; // 实现委托给私有片段里的 helper_add int add(int a, int b) { return helper_add(a, b); }// mathlib.impl.ixx（私有模块片段） module mathlib : private; // 这个函数不会出现在模块接口中，外部无法 import 或调用 int helper_add(int x, int y) { return x + y; }为什么不能直接在主模块里写实现？
如果所有代码都堆在 mathlib.ixx 里，哪怕函数没加 export，只要它被模块接口单元定义，就可能因 ODR 或隐式实例化暴露行为细节（比如模板内部使用的静态局部变量地址、内联展开痕迹）。更严重的是：一旦你想重构某个辅助逻辑，修改会强制所有依赖该模块的翻译单元重编译。
立即学习“C++免费学习笔记（深入）”；
使用私有模块片段后：
- 实现变更只影响主模块接口单元自身，不触发下游重编译（只要接口签名不变）
- ide 和构建系统能更好识别“哪些符号真正属于 ABI 边界”，提升索引准确性和构建缓存命中率
- 避免意外导出——比如忘了删掉某个
export，或误把Static函数写成全局导致链接冲突
常见错误和构建注意事项
MSVC 和 Clang 对模块片段的支持细节略有差异，尤其在路径解析和构建顺序上容易出问题：
-
import : private;必须出现在主模块接口的export module之后、首个export声明之前，否则 MSVC 报错：expected 'module' or 'import' before ':' - Clang 要求私有片段文件名必须与主模块同名（如
mathlib.impl.ixx），而 MSVC 更宽松，但建议统一遵守该命名约定 - CMake 中需确保私有片段被列为
target_sources(... PRIVATE)，且不参与install()——它不属于交付产物 - 不要试图在私有片段里
export module something_else;，这会让编译器认为你在定义新模块，而非片段
私有模块片段不是语法糖，它是模块系统中控制符号可见性的最小可信单元。漏掉 import : private; 或错放 export 是最常踩的两个坑，会导致符号找不到或编译失败，而且错误信息往往不直观。