头文件单元 ​

什么是头文件单元 ​

头文件单元(Header Unit)是 C++20 引入的一种机制,允许用 import 语句导入传统头文件。编译器会把头文件编译成一个合成的翻译单元,效果类似于模块——编译一次,多次导入,不需要每次都重新解析头文件的文本。

头文件单元是从 #include 向模块迁移的过渡方案。它既保留了头文件的兼容性(包括宏导出),又获得了部分模块化的好处(编译速度提升、更好的隔离)。

语法 ​

cpp
import <iostream>;      // 导入标准库头文件单元(尖括号)
import "myheader.h";    // 导入用户头文件单元(引号)

尖括号和引号的区别与 #include 一样——尖括号搜索系统/标准库路径,引号先搜索当前目录。

头文件单元 vs #include vs 命名模块 ​

方面#include <header>import <header>;import module;
处理方式文本替换(预处理器复制粘贴)编译成合成翻译单元预编译的模块接口
编译速度慢(每次包含都解析)较快(编译一次,多次导入)最快
宏导出导出(宏对包含者可见)导出(宏对导入者可见)不导出
宏影响包含者的宏影响头文件处理导入者的宏不影响头文件处理不涉及宏
声明归属属于包含它的翻译单元属于全局模块属于命名模块
隔离性无部分(宏隔离)完全

基本示例 ​

cpp
// ============================
// 示例1:导入标准库头文件单元
// ============================

// 文件:main.cpp
import <iostream>;      // 导入 iostream 头文件单元
import <vector>;        // 导入 vector 头文件单元
import <string>;        // 导入 string 头文件单元
import <algorithm>;     // 导入 algorithm 头文件单元

int main() {
    // 使用 vector 和 string
    std::vector<std::string> names{"Alice", "Bob", "Charlie"};

    // 使用 algorithm
    std::sort(names.begin(), names.end());

    // 使用 iostream
    for (const auto& name : names) {
        std::cout << name << std::endl;
    }

    return 0;
}
cpp
// ============================
// 示例2:在模块中使用头文件单元
// ============================

// 文件:logger.cppm(模块接口单元)
export module logger;

import <string>;        // 导入标准库头文件单元
import <iostream>;

export namespace logger {
    // 日志级别枚举
    enum class Level {
        Info,
        Warning,
        Error
    };

    // 获取级别的字符串表示
    const char* level_str(Level lv) {
        switch (lv) {
            case Level::Info:    return "[INFO]";
            case Level::Warning: return "[WARN]";
            case Level::Error:   return "[ERROR]";
        }
        return "[UNKNOWN]";
    }

    // 输出日志
    void log(Level lv, const std::string& message) {
        std::cout << level_str(lv) << " " << message << std::endl;
    }

    // 便捷函数
    void info(const std::string& msg)    { log(Level::Info, msg); }
    void warning(const std::string& msg) { log(Level::Warning, msg); }
    void error(const std::string& msg)   { log(Level::Error, msg); }
}

// ============================
// 文件:main.cpp
// ============================
import logger;
import <iostream>;

int main() {
    logger::info("程序启动");
    logger::warning("配置文件未找到,使用默认值");
    logger::error("连接超时");

    return 0;
}
cpp
// ============================
// 示例3:重新导出头文件单元
// ============================

// 文件:mylib.cppm
export module mylib;

// 重新导出头文件单元
// 导入 mylib 的翻译单元自动获得 iostream 和 string 的声明
export import <iostream>;
export import <string>;

export namespace mylib {
    void print(const std::string& msg) {
        std::cout << "[mylib] " << msg << std::endl;
    }
}

// ============================
// 文件:main.cpp
// ============================
import mylib;
// 不需要再 import <iostream> 或 import <string>
// 因为 mylib 已经重新导出了它们

int main() {
    std::string msg = "Hello from mylib";
    mylib::print(msg);

    // 直接使用 iostream——来自 mylib 重新导出的头文件单元
    std::cout << "直接使用 cout" << std::endl;

    return 0;
}

头文件单元的宏行为 ​

头文件单元与 #include 的一个关键区别在于宏的处理方式:

cpp
// 场景:头文件依赖外部宏来配置行为

// myconfig.h
#ifdef USE_FAST_MODE
    inline int compute() { return 42; }
#else
    inline int compute() { return 0; }
#endif

// === 用 #include 时 ===
#define USE_FAST_MODE         // 这个宏会影响 myconfig.h 的处理
#include "myconfig.h"         // compute() 返回 42

// === 用 import 头文件单元时 ===
#define USE_FAST_MODE         // 这个宏不会影响头文件单元的处理
import "myconfig.h";          // compute() 返回 0(USE_FAST_MODE 未定义)

这意味着:

  • 头文件单元的内容在编译时确定,不受导入者的宏影响
  • 如果头文件需要通过宏来配置,应该用全局模块片段 + #include,而不是 import

反过来,头文件单元中定义的宏会被导出到导入者:

cpp
// assert.h 中定义了 assert 宏

import <cassert>;   // assert 宏在导入者中可用
// assert(1 == 1);  // 可以使用

可导入头文件 ​

不是所有头文件都可以作为头文件单元导入。标准规定:

  • 所有标准 C++ 库头文件都是可导入的
  • C 标准库头文件(<cstdio>、<cstdlib> 等)是否可导入取决于编译器实现
  • 用户头文件是否可导入也取决于编译器实现

头文件不能作为头文件单元导入的常见原因:

  • 头文件中包含模块声明
  • 头文件定义了非 inline 的外部链接函数或变量
  • 头文件严重依赖包含顺序或外部宏

编译头文件单元 ​

不同编译器编译头文件单元的方式不同:

编译器编译命令示例
MSVC/exportHeader 选项或 VS 项目设置
GCC-x c++-header 标志
Clang--precompile 标志

MSVC 示例:

cl /std:c++20 /exportHeader /headerName:angle iostream
cl /std:c++20 /headerUnit:angle iostream=iostream.ifc main.cpp

适用场景 ​

  • 从 #include 向模块迁移的过渡期
  • 加速标准库头文件的编译
  • 在模块中使用标准库但编译器不支持 import std;
  • 逐步把项目中的头文件转换为模块

常见问题 ​

头文件单元和预编译头文件(PCH)有什么区别?

PCH 是编译器特有的优化,把一组头文件预编译成一个二进制文件。头文件单元是 C++ 标准的一部分,每个头文件单独编译成一个单元。PCH 是"全有或全无"的——要么全部预编译,要么不用。头文件单元更细粒度,可以按需导入。

import <header> 和 import "header" 的区别?

搜索路径不同,和 #include <header> vs #include "header" 一样。尖括号先搜索系统路径,引号先搜索当前目录。

头文件单元的宏会和命名模块中的宏行为一样吗?

不一样。命名模块不导出宏。头文件单元会导出其中定义的宏——这是为了和 #include 行为兼容。

所有编译器都支持头文件单元吗?

支持程度不同。MSVC 支持较好,GCC 和 Clang 有基本支持但可能不完整。在使用前需要确认你的编译器版本。

头文件单元可以重新导出吗?

可以。在模块接口单元中用 export import <header>; 即可重新导出头文件单元。

注意事项 ​

  • 头文件单元中定义的宏会导出到导入者
  • 导入者的宏不会影响头文件单元的处理
  • 不是所有头文件都能作为头文件单元导入
  • 头文件单元中不能有非 inline 的外部链接函数/变量定义
  • 编译构建系统需要配置才能支持头文件单元
  • 头文件单元的编译方式因编译器而异
  • 如果头文件依赖外部宏配置,用全局模块片段 + #include 而不是 import
  • C 标准库头文件的可导入性取决于编译器实现

编译器支持情况 ​

编译器最低支持版本标准库头文件单元用户头文件单元
MSVC19.28支持支持
GCC11.0有限有限
Clang16.0有限有限

总结 ​

头文件单元是 C++20 提供的一种将传统头文件以模块方式导入的机制。语法是 import <header>; 或 import "header";,编译器会把头文件编译成一个合成翻译单元。与 #include 相比,头文件单元编译一次多次使用,速度更快。与命名模块不同,头文件单元会导出其中定义的宏。一个重要的区别是导入者的宏不会影响头文件单元的处理——如果头文件需要宏配置,应该用全局模块片段中的 #include。头文件单元主要用作从 #include 向模块迁移的过渡方案,长期目标是用 import std; 等命名模块来替代。