模块接口单元应命名为math.ixx或utils.cppm等明确后缀，并在CMake中设置LANGUAGE CXX属性，且每个TU仅声明一个模块；export须在定义前，import不提供链接实现；宏在模块中不透出，需改用constexpr或条件导出。
模块接口单元怎么命名才不会被构建系统搞混
模块接口单元（module interface unit）的文件名本身不参与模块解析，但构建系统（如 CMake + clang 或 MSVC）依赖它推断编译行为。常见错误是用 math.cpp 或 utils.cc 这类传统后缀，导致编译器默认按普通翻译单元处理，import 失败且无明确报错。
- 必须使用明确标识模块意图的后缀：
.ixx（MSVC 推荐）、.cppm（clang/gcc 社区常用），或通过-x c++-system-header等显式指定，但后者易漏 - CMake 中需显式声明模块属性：
set_property(SOURCE math.ixx PROPERTY LANGUAGE CXX)，否则即使后缀正确，仍可能被跳过模块解析 - 避免在同一个
module interface unit里写多个module声明——C++20 规定一个 TU 最多一个模块声明，否则 clang 报error: module declaration must be the first non-comment, non-preprocessor token
import 和 export 的顺序为什么总导致链接失败
模块的导出与导入不是“声明即生效”，而是受编译器解析顺序和模块分区（partition）约束。典型现象是：头文件里能用的符号，在模块中 import 后却报 undefined reference，尤其涉及模板或内联函数。
-
export必须出现在符号定义之前，且不能跨分区隐式传递：比如export module math;后跟export template<typename T> T add(T a, T b) { return a + b; }是合法的；但如果把add定义放在另一个module partition里，又没在主接口中export import :detail;，那导入方就看不到它 -
import不等于“包含实现”，只建立编译期可见性；若模块中导出的是非内联函数，其定义仍需在某个module implementation unit（.cpp文件）里提供，否则链接阶段缺失符号 - 不要在模块接口里
#include <vector>后直接export using std::vector;——这会把标准库符号“污染”进你的模块接口，不同编译器对 std 模块的支持程度不同，MSVC 默认不启用std模块，clang 需要--std=c++20 -fmodules-ts配合预编译模块
CMake 构建大型项目时 modules 编译失败的三个硬伤
CMake 对 C++20 Modules 的支持仍处于“可用但脆弱”阶段，尤其在增量构建、跨目录依赖、缓存复用场景下容易静默失败。
- 模块二进制接口（BMI）路径必须绝对稳定：CMake 默认把 BMI 放在
CMAKE_CURRENT_BINARY_DIR下，但若多个子目录同时生成同名模块（如都叫core），会互相覆盖；应强制用set_target_properties(target PROPERTIES CXX_MODULE_DIALECT cxx20)并配合CXX_MODULE_OUTPUT_DIRECTORY指向唯一子目录 - 模块依赖图不能靠
target_link_libraries推导：CMake 不会自动从import语句反向建模，必须手动用target_compile_features+add_dependencies显式串起编译顺序，否则出现 “module ‘xxx’ not found” 却提示找不到源文件而非模块 - Clang 的
-fmodules-cache-path和 CMake 的CMAKE_CXX_MODULES_CACHE_PATH若未统一，会导致重复编译 BMI；而 MSVC 的/module:cache默认关，开之后又容易因路径含空格或 Unicode 崩溃
从头文件迁移到模块时哪些宏定义会失效
模块天然隔离预处理器作用域，所有在模块接口中定义的宏（#define）不会泄漏到导入方，这是优点也是坑点——很多老项目靠宏控制 ABI、调试开关或平台适配。
立即学习“C++免费学习笔记（深入）”；
-
#ifdef _DEBUG在模块内部有效，但导入方无法再用它控制模块行为；替代方案是导出 constexpr 变量：export constexpr bool is_debug_build = true;，或用模块参数化（需构建系统配合传参） - 像
BOOST_NO_EXCEPTIONS这类影响库行为的宏，若原头文件中靠它禁用异常路径，迁入模块后该宏无效，必须改用模块内条件编译或拆分接口（例如导出safe_add和throwing_add两个函数） - 模块不支持
#pragma once或#include式去重，所以旧代码里靠宏卫士（#ifndef XXX_H）防止重复定义的逻辑，在模块中完全多余，反而可能干扰 BMI 生成
模块不是编译加速的银弹，真正卡点往往不在语法转换，而在构建系统能否稳住 BMI 路径、能否让不同子模块的导出符号不冲突、以及是否意识到预处理器能力被主动放弃了——这些地方一松动，整个依赖重构就退回头文件时代。
