掌握C++20模块化：从头到尾的完整示例

2026-01-25 作者 stdcpp

C++20 推出了模块化（Modules）特性，旨在解决传统头文件的编译耦合问题。下面将通过一个完整的示例，演示如何定义、使用以及编译一个简单的模块，并结合常见的构建工具展示实战流程。

1. 目录结构

module_demo/
├─ src/
│  ├─ math.ixx          // 模块接口
│  ├─ math_impl.cpp     // 模块实现
│  ├─ main.cpp
├─ build/
├─ CMakeLists.txt

2. math.ixx – 模块接口文件

#pragma once

module math;

export module math;

export namespace Math {
    // 计算整数的阶乘
    int factorial(int n);
}

3. math_impl.cpp – 模块实现文件

module math;

#include <stdexcept>

namespace Math {
    int factorial(int n) {
        if (n < 0) throw std::invalid_argument("n must be non-negative");
        return (n <= 1) ? 1 : n * factorial(n - 1);
    }
}

注意：在实现文件中不需要 export，只在接口文件中使用 export 声明外部可见的符号。

4. main.cpp – 使用模块的程序

import math;          // 引入模块

#include <iostream>

int main() {
    for (int i = 0; i <= 5; ++i) {
        std::cout << i << "! = " << Math::factorial(i) << '\n';
    }
    return 0;
}

5. CMakeLists.txt – 构建配置

cmake_minimum_required(VERSION 3.23)   # 需支持 C++20 模块
project(ModuleDemo LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# 编译选项
add_compile_options(-fmodules-ts -fimplicit-inline-templates)

# 生成模块
add_library(math MODULE src/math.ixx src/math_impl.cpp)

# 把模块导出到全局可见目录
target_compile_options(math PRIVATE -fmodules-ts)
target_link_options(math PRIVATE -fmodules-ts)

# 可执行文件
add_executable(module_demo src/main.cpp)
target_link_libraries(module_demo PRIVATE math)

说明

-fmodules-ts 是 GCC/Clang 对模块技术规范（TS）的实现开关；在较新的版本已默认开启。

MODULE 关键字创建一个模块化目标。

6. 编译运行

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

输出：

0! = 1
1! = 1
2! = 2
3! = 6
4! = 24
5! = 120

7. 常见问题解答

问题	解决方案
编译器报错 `error: cannot load module interface`	确认 `CMakeLists.txt` 中使用了 `MODULE` 而不是 `STATIC` 或 `SHARED`。
模块在不同编译单元中重复定义	确保只在 `.ixx` 接口文件中使用 `export`，实现文件不重复导出。
头文件与模块混用导致编译时间反而变长	彻底替换为模块化；若仍需头文件，可使用 `-fno-implicit-modules`。

8. 小结

通过上述步骤，你可以在 C++20 环境下完整地实现并使用模块。模块化带来的优势包括：

编译速度提升：避免重复解析头文件。
符号可见性更精确：只导出 export 的符号。
更好的语言集成：模块可以与 C++ 标准库、第三方库无缝协作。

掌握模块化是迈向现代 C++ 的关键一步，建议在新项目中优先考虑使用。

发表评论取消回复