C++20 Modules支持需编译器满足最低版本：GCC 11.1+、Clang 13.0+、MSVC VS2019 16.8+，并正确启用对应标志；模块接口单元用.export module声明，以.import替代#include，构建系统需CMake 3.24+且禁用PCH。
确认编译器版本是否支持 C++20 Modules
模块功能在 C++20 中标准化，但各编译器实现进度不同。不满足最低版本要求时，import 会直接报错，不是配置问题而是语言特性不可用。
- GCC：需
11.1+（实验性支持），推荐12.2+；启用需加-fmodules-ts（旧）或-std=c++20 -fmodules（新） - Clang：需
13.0+；启用需-std=c++20 -fmodules -fimplicit-modules -fimplicit-module-maps - MSVC：VS 2019 16.8+ 开始支持，但必须用
/std:c++20 /experimental:module，且项目类型需为“常规”而非“CMake”（后者模块支持仍受限）
运行 g++ --version 或 clang++ --version 验证；若版本过低，先升级工具链——否则后续所有迁移都是徒劳。
将传统头文件拆分为 module interface unit（.ixx 或 .cppm）
模块接口单元是模块的“门面”，它声明导出内容，不包含实现细节（除非是内联函数）。不能混用 #include 和 export module 在同一文件中。
- 文件扩展名：MSVC 强制用
.ixx；GCC/Clang 推荐.cppm（避免与预编译头冲突） - 基本结构：
export module math_utils;
export int add(int a, int b); export namespace detail { constexpr int max_value = 100; }
- 禁止在 interface unit 中写非导出定义（如普通函数体、全局变量定义），否则编译失败或链接重复定义
- 若需复用现有头文件（如
utils.h），可用export import封装，但要注意：该头文件必须满足模块友好的条件（无宏污染、无依赖未声明符号）
修改源文件：用 import 替代 #include，并处理 ODR 和初始化顺序
import 不是文本替换，它引入的是已编译的模块接口，因此不再有头文件卫士、宏传播、多次包含等问题——但这也意味着你不能再依赖 #define 跨模块生效，也不能靠 #include 顺序控制初始化时机。
立即学习“C++免费学习笔记（深入）”；
- 替换规则：
#include "math_utils.h"→import math_utils;（模块名由module声明决定，与文件名无关） - 全局对象初始化：模块中
export inline变量或constinit变量的初始化顺序，不保证跨模块一致；若原有代码依赖static全局对象构造顺序，必须显式重构为函数调用或延迟初始化 - ODR（One Definition Rule）更严格：两个模块不能导出同名非内联函数；若旧项目有多个
utils.cpp定义了相同helper()，必须统一归口或改名，否则链接失败
调整构建系统：CMake 3.24+ 是底线，且需禁用 PCH 和旧式头文件缓存
CMake 对模块的支持仍处于演进中。低于 3.24 的版本无法正确生成 module map 或依赖图，强行使用会导致构建中断或二进制不一致。
- CMakeLists.txt 示例：
set(CMAKE_CXX_STANDARD 20) set(CMAKE_CXX_EXTENSIONS OFF)
启用模块支持（GCC/Clang）
if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang") set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fmodules") endif()
声明模块接口文件
add_library(math_utils MODULE math_utils.cppm) target_compile_options(math_utils PRIVATE -fmodule-mapper=build/module-map.json)
注意：实际需配合 module map 生成逻辑，推荐用 CMake 3.27+ 的
cmake_file_api自动管理 - 必须关闭预编译头（PCH）：模块和 PCH 机制互斥，启用
target_precompile_headers会导致import解析失败 - 清理旧缓存：
rm -rf CMakeFiles/ cmake-build-*，否则 CMake 可能沿用旧的头文件依赖信息，导致模块未被识别
模块路径解析、二进制接口稳定性、跨编译单元的模板实例化共享——这些都不是“开关一开就跑通”的事情。最容易卡住的地方其实是构建系统的 module map 生成逻辑和 IDE 索引（如 VS Code 的 C++ extension 对 .ixx 支持仍不稳定），建议先拿一个最小可运行模块验证端到端流程，再逐步迁移。
