模块接口单元首行必须为 export module modulename;，否则编译器无法识别；所有对外暴露的声明须加 export 修饰符；禁止使用 #include 和宏定义，因 import 加载的是已编译的 bmi，不进行文本替换。
模块接口单元必须用 export module 显式声明
头文件被重复包含，本质是预处理器无差别粘贴文本；而模块接口单元（如 .ixx 或 .cppm）必须以 export module 开头，这是编译器识别“这是一个独立编译单元”的唯一信号。不写这行，或写成 module（没 export），编译器会当成普通实现单元甚至报错 module declaration not found。
常见错误现象：
- 把旧
.h文件直接改后缀为.ixx，但没加export module，结果所有import都失败 - 在接口单元里漏掉
export修饰符，函数/类看似写了，实际对外不可见，链接时报undefined reference
实操建议：
- 接口单元第一行必须是
export module MyModule;，模块名建议用 PascalCase，避免与标准库或第三方模块重名 - 所有要暴露给外部的声明（函数、类、变量、
namespace）前必须加export，哪怕它在一个export namespace内部 - 不要在接口单元里写
#include—— 它不是头文件，不需要靠宏卫士或前置声明来防重入
import 不会触发宏传播，但也不能读取宏定义
宏污染消失，是因为 import 不做文本替换，而是加载已编译的模块接口（BMI），其中不含任何预处理状态。这意味着：你在模块 A 里 #define LOG(x) std::cout ，模块 B <code>import A 后，LOG 不可用；反过来，模块 B 自己定义的宏，也绝不会穿透进模块 A 的编译上下文。
这带来两个现实影响：
- 旧项目里靠宏控制接口开关（如
#ifdef ENABLE_FOO）的模式，在模块中失效 —— 必须改用constexpr bool或模板参数 - 跨模块日志、断言等基础设施，不能再依赖全局宏，得封装成
export函数或内联变量
实操建议：
- 把所有功能开关型宏转为
export inline constexpr bool enable_foo = true;，既可导出，又保持编译期常量语义 - 如果必须保留宏（比如对接 C 风格 API），只能放在单独的“兼容头文件”中，并明确标注
// NOT for module use，禁止import方包含它 - 调试时发现某个符号行为异常？先检查是否误用了宏定义 —— 模块里查不到宏，就说明它根本没生效
模块不能递归 import 自身，循环依赖会被编译器硬拦
头文件能靠 #pragma once 或 #ifndef 实现“软防循环”，但只是阻止重复展开，不解决逻辑耦合。模块不同：import 是语义级依赖声明，编译器在解析接口单元时就构建依赖图，一旦检测到 A → B → A，直接报错 circular import detected，不给编译机会。
这不是限制，而是强制你面对真实依赖问题。很多“头文件地狱”项目，表面看没循环 #include，实则通过中间头文件暗渡陈仓，模块把这个黑盒彻底掀开。
实操建议：
- 遇到循环 import，别急着拆分区（
module :partition），先问：这两个模块是否本该合并？或者其中一方是否该降级为私有实现片段（module :private）？ - 若确需解耦，引入一个第三模块（如
CoreTypes）导出共用类型，A 和 B 都import CoreTypes，但互不 import - 注意：
import顺序无关紧要，模块依赖图由符号引用关系决定，不是代码书写顺序
CMake 构建时必须启用模块感知，否则 import 会找不到 BMI
即使语法全对，import MathUtils 仍可能报 module 'MathUtils' not found —— 这通常不是路径问题，而是 CMake 没告诉编译器“去哪找已生成的 BMI 文件”。GCC/Clang 要求显式传 -fmodules-ts（C++20 前）或 -std=c++20 -fmodules，且必须确保模块接口单元先于导入方编译。
MSVC 更严格：不仅需要 /std:c++20 /experimental:module，还要求模块接口单元用 .ixx 后缀，并在 target_sources 中标记为 MODULE_INTERFACE。
实操建议：
- 用 CMake 3.28+，对模块接口单元调用
target_sources(mylib PRIVATE mymodule.ixx)，并确保set_property(SOURCE mymodule.ixx PROPERTY LANGUAGE CXX) - 避免在同一个
add_library中混用模块接口和传统头文件 —— 构建系统容易混淆依赖拓扑 - 调试 BMI 路径：编译时加
-v（Clang/GCC）或/verbosity:diag（MSVC），看输出里是否出现building module 'MyModule'及对应 BMI 路径
export 和物理隔离定义的契约。一旦接口单元里漏了一个 export，或构建系统没把 BMI 放进搜索路径，问题就会卡在链接层，而不是编译报错——这种延迟失败最耗时间。C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
