头文件单元
什么是头文件单元
头文件单元(Header Unit)是 C++20 引入的一种机制,允许用 import 语句导入传统头文件。编译器会把头文件编译成一个合成的翻译单元,效果类似于模块——编译一次,多次导入,不需要每次都重新解析头文件的文本。
头文件单元是从 #include 向模块迁移的过渡方案。它既保留了头文件的兼容性(包括宏导出),又获得了部分模块化的好处(编译速度提升、更好的隔离)。
语法
import <iostream>; // 导入标准库头文件单元(尖括号)
import "myheader.h"; // 导入用户头文件单元(引号)尖括号和引号的区别与 #include 一样——尖括号搜索系统/标准库路径,引号先搜索当前目录。
头文件单元 vs #include vs 命名模块
| 方面 | #include <header> | import <header>; | import module; |
|---|---|---|---|
| 处理方式 | 文本替换(预处理器复制粘贴) | 编译成合成翻译单元 | 预编译的模块接口 |
| 编译速度 | 慢(每次包含都解析) | 较快(编译一次,多次导入) | 最快 |
| 宏导出 | 导出(宏对包含者可见) | 导出(宏对导入者可见) | 不导出 |
| 宏影响 | 包含者的宏影响头文件处理 | 导入者的宏不影响头文件处理 | 不涉及宏 |
| 声明归属 | 属于包含它的翻译单元 | 属于全局模块 | 属于命名模块 |
| 隔离性 | 无 | 部分(宏隔离) | 完全 |
基本示例
// ============================
// 示例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;
}// ============================
// 示例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;
}// ============================
// 示例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 的一个关键区别在于宏的处理方式:
// 场景:头文件依赖外部宏来配置行为
// 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
反过来,头文件单元中定义的宏会被导出到导入者:
// 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 标准库头文件的可导入性取决于编译器实现
编译器支持情况
| 编译器 | 最低支持版本 | 标准库头文件单元 | 用户头文件单元 |
|---|---|---|---|
| MSVC | 19.28 | 支持 | 支持 |
| GCC | 11.0 | 有限 | 有限 |
| Clang | 16.0 | 有限 | 有限 |
总结
头文件单元是 C++20 提供的一种将传统头文件以模块方式导入的机制。语法是 import <header>; 或 import "header";,编译器会把头文件编译成一个合成翻译单元。与 #include 相比,头文件单元编译一次多次使用,速度更快。与命名模块不同,头文件单元会导出其中定义的宏。一个重要的区别是导入者的宏不会影响头文件单元的处理——如果头文件需要宏配置,应该用全局模块片段中的 #include。头文件单元主要用作从 #include 向模块迁移的过渡方案,长期目标是用 import std; 等命名模块来替代。