import不生效的根本原因是模块接口单元未被编译器识别或构建系统未启用模块支持，需确保C++20标准、正确文件后缀、export修饰符及构建顺序。
为什么 import 不生效，编译器报 “module not found”
根本原因通常是模块接口单元（.ixx 或 .cppm）没被编译器识别为模块，或构建系统未启用模块支持。MSVC 默认不自动处理模块文件，Clang/GCC 也需显式开关。
- 确保使用 C++20 标准：MSVC 加
/std:c++20，Clang 加-std=c++20 -fmodules，GCC 11+ 需-std=c++20 -fmodules-ts（注意 GCC 的 TS 模式与标准有差异） - 模块接口文件必须以
export module开头，且不能包含#include（除非用import替代） - MSVC 要求模块接口单元后缀为
.ixx（推荐）或.cppm；Clang 建议用.cppm；GCC 对后缀不敏感但需在命令行显式声明为模块 - 构建顺序不能乱：模块接口单元必须先于导入它的源文件编译，否则
import找不到二进制模块接口（BMI）
export module 和 export import 的实际分工
模块声明不是“导出整个文件”，而是精确控制符号可见性。接口单元中只有被 export 修饰的声明才对外可见。
-
export module math.utils;—— 定义模块名，不导出任何符号 -
export int add(int a, int b) { return a + b; }—— 导出函数定义（内联函数可直接定义） -
export namespace math { class Calculator { ... }; }—— 导出整个命名空间 -
export import :detail;—— 导出私有分区（:detail）中的内容，相当于“受控的内部实现暴露” - 非
export的声明（如辅助函数、静态变量）仅在本模块内可用，不会污染导入者的全局命名空间
CMake 中启用模块的三个硬性步骤
CMake 3.27+ 原生支持模块，但旧版本或跨编译器时极易漏掉关键配置。以下缺一不可：
- 设置项目标准：
set(CMAKE_CXX_STANDARD 20)且set(CMAKE_CXX_STANDARD_REQUIRED ON) - 为模块接口文件单独设置属性：
set_source_files_properties(math.ixx PROPERTIES LANGUAGE CXX HEADER_FILE_ONLY OFF MODULE_INTERFACE ON)
- 显式启用模块输出：
target_compile_options(myapp PRIVATE $:/interface>)（MSVC）或$:-fmodules-cache-path=build/modules>（Clang）
从头文件迁移到模块时最常踩的五个坑
不是简单把 #include "foo.h" 改成 import foo; 就完事。模块改变了依赖解析模型，很多隐式假设会崩塌。
- 宏不再跨模块传递：
#define LOG_LEVEL 2在模块 A 中定义，模块 Bimport A;后无法使用该宏 —— 模块不传播预处理器状态 - 模板显式实例化需在模块内完成：
template class std::vector若写在模块接口里，必须确保该实例化语句本身被; export，否则链接时报 undefined symbol - 第三方库仍用头文件？得桥接：
import可用，但import "boost/filesystem.hpp"不合法 —— 必须用module boost_filesystem : header "boost/filesystem.hpp";声明头文件模块（Clang/MSVC 支持，GCC 不支持） - 模块名不能含点号但路径可以：
export module my.是非法的（
lib.core;
.不是合法标识符），应写作export module my_lib_core;或用斜杠风格（MSVC 支持export module my/lib/core;） - 调试信息错位：某些调试器（如早期 VS Code + MSVC）无法在模块接口单元中设断点，建议将复杂逻辑下沉到模块实现单元（
.cpp），接口只留声明
export 显式收口。一个没加 export 的类，哪怕写在 .ixx 里，对使用者来说就等于不存在。
