在 C++20 之后，模块化成为了 C++ 生态中一大热点。相比传统的预编译头文件（PCH），模块化在编译速度、命名空间污染以及二进制接口（ABI）可维护性方面都拥有明显优势。本文将从零开始，演示如何创建一个简单的 C++20 模块化库，并提供完整的构建脚本与常见陷阱分析，帮助你快速落地实际项目。
一、项目结构
/modlib
├─ src
│ ├─ math.cpp # 模块实现
│ └─ math.hpp # 纯声明头文件（可选）
├─ mod
│ ├─ math.ixx # 模块接口文件
│ └─ math.h # 传统头文件（兼容旧代码）
├─ test
│ └─ main.cpp # 使用模块的客户端
├─ CMakeLists.txt
└─ README.md
math.ixx：C++20 模块的核心文件，定义模块接口（export module math;）以及导出的实体。math.h：可选的“shim”头文件，用于在不支持模块的编译器或老代码中继续使用 #include "math.h"。它内部使用 export import math; 进行模块导入。math.cpp：实现文件，用于编译生成模块对象文件（math.pcm）和静态/动态库。
二、模块接口文件（math.ixx）
#pragma once
export module math; // ① 声明模块名
export namespace math { // ② 创建导出的命名空间
export inline double add(double a, double b) {
return a + b;
}
export struct Vector2D {
double x, y;
export double length() const {
return std::hypot(x, y);
}
};
}
export module math;：模块声明，所有文件共同属于此模块。 export namespace math：通过 export 标记，模块内的实体对外可见。 inline 函数：C++20 允许在模块接口中直接定义（inline）函数，不需要单独的实现文件。
小技巧：如果你想在模块中使用第三方库（如 std::hypot），记得在模块接口顶部添加 `import
;` 或 `export import ;`。
三、传统头文件（math.h）
#pragma once
export import math; // 让旧代码仍然能 `#include "math.h"`
这份头文件仅是为了兼容不支持模块的编译器或旧项目。它不含任何实现，所有内容都来自 math.ixx。
四、实现文件（math.cpp）
如果你需要在模块中实现非 inline 的函数或类成员，你可以在实现文件中包含模块接口：
module math; // ① 必须先引入模块接口
export double multiply(double a, double b) {
return a * b;
}
编译后将得到 math.pcm（模块对象文件）以及可供链接的 math.lib / libmath.so。
五、CMake 构建脚本
cmake_minimum_required(VERSION 3.22)
project(ModLib LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
# 1. 编译模块对象
add_library(math_obj OBJECT src/math.cpp mod/math.ixx)
target_compile_options(math_obj PRIVATE -fmodules-ts) # 对于 GCC/Clang
target_link_libraries(math_obj PRIVATE math_obj) # 对于 MSVC，自动处理
# 2. 创建静态库
add_library(math STATIC $<TARGET_OBJECTS:math_obj>)
target_include_directories(math PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/mod)
# 3. 生成共享库（可选）
add_library(math_shared SHARED $<TARGET_OBJECTS:math_obj>)
set_target_properties(math_shared PROPERTIES OUTPUT_NAME "math")
# 4. 测试可执行文件
add_executable(mod_test test/main.cpp)
target_link_libraries(mod_test PRIVATE math)
# 5. 生成旧头文件兼容版本
add_custom_target(math_header ALL
COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_SOURCE_DIR}/mod/math.h
${CMAKE_CURRENT_BINARY_DIR}/include/math.h
DEPENDS mod/math.h)
说明
add_library(math_obj OBJECT ...) 用来生成模块对象文件。 -fmodules-ts 是 Clang / GCC 的实验性模块支持标志，MSVC 不需要。 math.h 的生成是可选的，只在你需要兼容旧项目时使用。
六、客户端代码（test/main.cpp）
#include <iostream>
import math; // C++20 模块导入
int main() {
double a = 3.14, b = 2.71;
std::cout << "add: " << math::add(a, b) << '\n';
std::cout << "multiply: " << math::multiply(a, b) << '\n';
math::Vector2D v{3, 4};
std::cout << "vector length: " << v.length() << '\n';
}
如果你使用的是旧编译器或没有模块支持的 IDE，只需改为：
#include "math.h" // 旧头文件
七、常见问题与最佳实践
| 场景 |
常见错误 |
解决方案 |
| 模块依赖 |
多模块间互相引用导致循环 |
使用 `export import |
| ;` 前先确保模块已完整编译，避免循环依赖，或拆分模块 |
| 编译缓存 |
旧对象文件残留导致不一致 |
每次改动模块接口后清理 CMakeCache.txt 并执行 cmake --build . --clean-first |
| ABI 兼容 |
直接将模块编译为静态库，跨编译器链接出现错误 |
采用 -fvisibility=hidden 并显式导出 export，或者使用 -fvisibility-inlines-hidden |
| 头文件兼容 |
`#include |
在模块中导致符号冲突 | 在模块内部使用import ;，在旧头文件中直接包含math.h` 以隐藏冲突 |
| IDE 支持 |
Visual Studio 2022 仅支持 export 关键字，旧版不识别 |
在项目中使用 CMake 并确保生成的 .vcxproj 采用 ModuleDefinitionFile |
| 编译器差异 |
Clang 与 GCC 对模块实现细节不同 |
使用 -fmodules-ts，并根据不同编译器调整 CMAKE_CXX_FLAGS |
八、总结
C++20 模块化为现代 C++ 开发带来了前所未有的性能与可维护性提升。通过本文的完整示例，你可以：
- 快速上手：了解模块的核心语法与实现方式。
- 构建规范：借助 CMake 脚本实现模块编译、兼容性与可链接性。
- 解决常见陷阱：提前规避循环依赖、编译缓存与 ABI 兼容性等问题。
下一步，你可以尝试扩展 math 模块，添加更多子模块（如 geometry、algebra）并实现更复杂的模板元编程特性。祝你编码愉快，模块化之路畅通无阻！
