掌握 C++20 模块化编程：从头到尾的实战指南

C++20 引入了模块化编程的概念，旨在解决传统头文件（header-only）编译速度慢、命名空间污染等问题。本文将通过一步一步的示例，帮助你快速上手模块化编程，并演示如何在一个完整的项目中使用模块。

一、什么是模块？

模块是一组相关的声明（包括类型、函数、变量等），通过一个单独的文件（模块接口文件）来声明，对外只暴露需要的接口。编译器会把这些声明编译成 模块接口单元（.ifc），随后可以被其它翻译单元（.cpp）导入。
相比头文件，模块具有以下优点：

优点	传统头文件	C++20 模块
编译速度	每次包含都会重新编译	只编译一次，后续仅链接
隐私控制	需手动使用 `#ifdef` 或 `namespace`	自动隐藏未导出的符号
并发编译	头文件全局可见	只在接口单元内可见，减少依赖冲突
语义检查	预处理器无类型检查	编译器能做完整语义检查

二、准备工作

编译器：Clang 12+、GCC 10+、MSVC 16.11+ 均已支持 C++20 模块。
构建工具：CMake 3.20+（推荐）或 Make。

项目结构：

/my_project
├── CMakeLists.txt
├── src
│   ├── main.cpp
│   ├── math
│   │   ├── math.ifc
│   │   └── math.cpp
│   └── utils
│       ├── utils.ifc
│       └── utils.cpp
└── include
 └── common.h

*.ifc 为模块接口文件
*.cpp 为实现文件
common.h 为传统头文件（演示兼容性）

三、模块接口文件 `math.ifc`

// math.ifc
#pragma once
export module math; // 声明模块名称

export namespace math {
    // 计算斐波那契数
    inline int fib(int n) {
        if (n <= 1) return n;
        return fib(n-1) + fib(n-2);
    }

    // 仅导出的类型
    export struct Complex {
        double real, imag;
        Complex(double r = 0, double i = 0) : real(r), imag(i) {}
    };
} // namespace math

export module math; 让编译器知道这是 math 模块。
export 关键字用来标记需要导出的声明。

四、实现文件 `math.cpp`

// math.cpp
module math; // 引入同一模块的实现单元
// 不需要 export，所有未显式 export 的内容默认是实现细节
// 这里演示如何把实现拆分成独立文件
namespace math {
    struct Helper {
        static int helper_func(int n) {
            // 递归调用会被编译器优化为尾递归
            return fib(n-1) + fib(n-2);
        }
    };
}

实现文件不需要再声明 export，它只属于模块内部。

五、另一模块 `utils.ifc`

// utils.ifc
#pragma once
export module utils;
export namespace utils {
    export void print(const char* msg);
}

实现文件 utils.cpp：

// utils.cpp
module utils;
import <iostream>; // 标准库头文件
namespace utils {
    void print(const char* msg) {
        std::cout << msg << '\n';
    }
}

六、主程序 `main.cpp`

// main.cpp
import math;   // 引入 math 模块
import utils;  // 引入 utils 模块
import <iostream>; // 传统头文件

int main() {
    utils::print("C++20 模块化编程 Demo");
    std::cout << "fib(10) = " << math::fib(10) << '\n';
    math::Complex c(3.0, 4.0);
    std::cout << "Complex: (" << c.real << ", " << c.imag << "i)\n";
    return 0;
}

七、CMake 配置 `CMakeLists.txt`

cmake_minimum_required(VERSION 3.20)
project(ModuleDemo LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

add_executable(module_demo
    src/main.cpp
    src/math/math.cpp
    src/utils/utils.cpp
)

# 指定模块编译
target_sources(module_demo PRIVATE
    src/math/math.ifc
    src/utils/utils.ifc
)

# 需要为模块接口文件添加编译选项
target_compile_options(module_demo PRIVATE
    $<$<COMPILE_LANGUAGE:CXX>:-fmodules-ts>
)

# 对于 Clang 或 GCC 需要开启模块支持
if(CMAKE_CXX_COMPILER_ID MATCHES "Clang|GNU")
    target_compile_options(module_demo PRIVATE
        -fmodules-ts
    )
endif()

注意

Clang 需要 -fmodules-ts 选项才能开启实验性模块支持。

GCC 10+ 在默认开启 C++20 时已支持模块。

MSVC 需要 /std:c++latest 并开启 module 支持。

八、编译与运行

mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build .
./module_demo

输出示例：

C++20 模块化编程 Demo
fib(10) = 55
Complex: (3, 4i)

九、常见问题排查

模块接口未被正确编译
- 检查 *.ifc 是否被 target_sources 添加。
- 确认编译器支持模块并开启相应标志。
符号冲突
- 模块内部未导出的符号对外不可见，减少冲突。
- 若需要共享同名符号，使用 export 明确导出。
性能
- 模块编译后生成的接口单元可缓存，后续编译速度提升显著。
- 适合大型项目或频繁编译的单元。

十、总结

C++20 模块化编程为 C++ 带来了显著的编译效率提升和代码封装能力。通过以上示例，你已经学会了：

如何编写模块接口文件（.ifc）
如何实现模块内部细节
如何在项目中导入和使用模块
如何使用 CMake 配置模块化项目

现在就把这些知识运用到你自己的项目中，体验模块带来的高效与整洁吧！

一、什么是模块？

二、准备工作

三、模块接口文件 math.ifc

四、实现文件 math.cpp

五、另一模块 utils.ifc

六、主程序 main.cpp

七、CMake 配置 CMakeLists.txt