C++20 模块：在项目中如何快速上手与实践

2026-01-28 作者 stdcpp

在 C++20 标准中引入了模块（Modules）功能，旨在解决传统头文件所带来的编译效率低下和符号冲突等问题。本文将从概念讲起，演示如何在一个简单的 C++20 项目中引入模块，编译并运行，帮助读者快速掌握模块的使用方法。

1. 模块概念回顾

模块（Module）是一组相关的源文件，打包成一个编译单元。
通过 export 关键字暴露接口，内部实现细节被隐藏。
与传统头文件相比，模块避免了重复解析、宏污染以及编译时间膨胀。

2. 项目结构示例

/modules-demo
├─ src
│   ├─ math
│   │   ├─ math.hpp
│   │   ├─ math.cpp
│   │   └─ math.modulerc
│   └─ main.cpp
└─ build

2.1 math.modulerc

module interface math
export module math;
export interface {
    int add(int a, int b);
    int sub(int a, int b);
}
implementation {
    int add(int a, int b) { return a + b; }
    int sub(int a, int b) { return a - b; }
}

这里 math.modulerc 使用了 模块复合文件（module interface unit），将接口和实现放在一起，简化示例。

2.2 math.hpp

#pragma once
export module math;

export int add(int a, int b);
export int sub(int a, int b);

#pragma once 在模块中不必要，但保留可避免不兼容编译器的问题。

2.3 math.cpp

module math;

// 实现细节（可以是大文件）
int add(int a, int b) { return a + b; }
int sub(int a, int b) { return a - b; }

2.4 main.cpp

import math;   // 引入模块

#include <iostream>

int main() {
    std::cout << "add(3, 4) = " << add(3, 4) << std::endl;
    std::cout << "sub(10, 6) = " << sub(10, 6) << std::endl;
    return 0;
}

3. 编译与运行

3.1 使用 GCC 12+

# 编译模块
g++ -std=c++20 -fmodules-ts -c src/math.cpp -o build/math.o
# 编译主程序
g++ -std=c++20 -fmodules-ts -c src/main.cpp -o build/main.o
# 链接
g++ -std=c++20 -fmodules-ts build/math.o build/main.o -o build/modules_demo
# 运行
./build/modules_demo

3.2 使用 Clang 15+

Clang 通过 -fmodules 选项实现模块支持，编译过程与 GCC 类似。

clang++ -std=c++20 -fmodules -c src/math.cpp -o build/math.o
clang++ -std=c++20 -fmodules -c src/main.cpp -o build/main.o
clang++ -std=c++20 -fmodules build/math.o build/main.o -o build/modules_demo
./build/modules_demo

3.3 使用 CMake

如果项目较大，建议使用 CMake 的模块支持。示例 CMakeLists.txt：

cmake_minimum_required(VERSION 3.24)
project(modules_demo LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

add_library(math STATIC src/math.cpp)
target_compile_options(math PRIVATE -fmodules-ts)

add_executable(modules_demo src/main.cpp)
target_link_libraries(modules_demo PRIVATE math)
target_compile_options(modules_demo PRIVATE -fmodules-ts)

执行：

mkdir build && cd build
cmake ..
cmake --build .
./modules_demo

4. 常见问题与解决

问题	可能原因	解决办法
编译报错：`module` 关键字未识别	编译器未开启模块支持	使用 `-fmodules-ts`（GCC）或 `-fmodules`（Clang）
`import` 语句找不到模块	模块文件未正确编译或路径错误	确认模块被编译为 `.o` 并在链接时包含
运行时符号未定义	模块接口未导出实现	确认 `export` 放置在接口声明处，且实现文件使用 `module math;`
与旧代码混合使用 `#include`	模块与头文件混用可能导致二次编译	将旧文件改为模块，或在模块内部使用 `#include` 但不导出

5. 小结

模块通过接口与实现的分离，显著提升编译效率。
只需少量改动即可将传统库转换为模块化结构。
GCC 与 Clang 在 C++20 模块方面已基本成熟，使用 -fmodules-ts 或 -fmodules 开启即可。

掌握模块后，你可以进一步探索 模块缓存（Module Cache）、多模块编译 与 跨平台模块构建，让 C++ 项目更易维护、编译更快。祝你编码愉快！

发表评论取消回复