__has_include 预处理指令
什么是 __has_include
__has_include 是 C++17 标准化的一个预处理器特性,用来在编译前检测某个头文件是否可用。它在 #if / #elif 预处理指令中使用,如果指定的头文件存在(能被编译器找到),表达式求值为 1;否则求值为 0。
在 C++17 之前,想知道某个头文件是否存在,只能靠构建系统(CMake 的 check_include_file)或平台/编译器宏来间接判断。__has_include 让这件事变得简单直接——在源代码中就能完成,不依赖外部构建配置。
这个特性在 Clang 中早已作为编译器扩展存在多年,C++17 将其正式纳入标准。
语法
// 检查系统头文件(用尖括号)
#if __has_include(<header_name>)
// 检查本地头文件(用双引号)
#if __has_include("header_name")它只能出现在 #if、#elif 等预处理条件表达式中,不能在普通 C++ 代码中使用。
为了兼容不支持 __has_include 的旧编译器,通常先检查 __has_include 本身是否可用:
#ifdef __has_include
# if __has_include(<optional>)
# include <optional>
# endif
#endif基本示例
// ============================
// 示例1:检测 C++17 optional 是否可用
// ============================
#ifdef __has_include
# if __has_include(<optional>)
# include <optional>
# define HAS_OPTIONAL 1
# elif __has_include(<experimental/optional>)
// 回退到实验性版本(某些较旧的编译器提供)
# include <experimental/optional>
# define HAS_OPTIONAL 1
# define OPTIONAL_IS_EXPERIMENTAL 1
# else
# define HAS_OPTIONAL 0
# endif
#else
# define HAS_OPTIONAL 0
#endif
#include <iostream>
#include <string>
// 根据是否有 optional 提供不同的实现
#if HAS_OPTIONAL
#ifndef OPTIONAL_IS_EXPERIMENTAL
using std::optional;
#else
using std::experimental::optional;
#endif
optional<std::string> find_user(int id) {
if (id == 1) return "Alice";
return std::nullopt; // 或 {}
}
#else
// 没有 optional 时的回退实现
std::string find_user(int id) {
if (id == 1) return "Alice";
return ""; // 用空字符串表示"没找到"
}
#endif
int main() {
#if HAS_OPTIONAL
auto user = find_user(1);
if (user) {
std::cout << "找到用户: " << *user << std::endl;
}
std::cout << "使用 std::optional 实现" << std::endl;
#else
auto user = find_user(1);
if (!user.empty()) {
std::cout << "找到用户: " << user << std::endl;
}
std::cout << "使用回退实现" << std::endl;
#endif
return 0;
}// ============================
// 示例2:检测文件系统库
// ============================
#ifdef __has_include
# if __has_include(<filesystem>)
# include <filesystem>
namespace fs = std::filesystem;
# elif __has_include(<experimental/filesystem>)
# include <experimental/filesystem>
namespace fs = std::experimental::filesystem;
# else
# error "需要 <filesystem> 支持"
# endif
#endif
#include <iostream>
int main() {
// 不管是标准版还是实验版,都用 fs 命名空间
fs::path p = fs::current_path();
std::cout << "当前目录: " << p << std::endl;
return 0;
}// ============================
// 示例3:检测平台特定的头文件
// ============================
#include <iostream>
#ifdef __has_include
# if __has_include(<unistd.h>)
# define PLATFORM_POSIX 1
# elif __has_include(<windows.h>)
# define PLATFORM_WINDOWS 1
# endif
#endif
void print_platform() {
#if defined(PLATFORM_POSIX)
std::cout << "POSIX 平台" << std::endl;
#elif defined(PLATFORM_WINDOWS)
std::cout << "Windows 平台" << std::endl;
#else
std::cout << "未知平台" << std::endl;
#endif
}
int main() {
print_platform();
return 0;
}// ============================
// 示例4:检测第三方库是否安装
// ============================
#include <iostream>
#ifdef __has_include
# if __has_include(<nlohmann/json.hpp>)
# include <nlohmann/json.hpp>
# define HAS_JSON 1
# endif
# if __has_include(<fmt/core.h>)
# include <fmt/core.h>
# define HAS_FMT 1
# endif
# if __has_include(<boost/asio.hpp>)
# define HAS_BOOST_ASIO 1
# endif
#endif
int main() {
#ifdef HAS_JSON
std::cout << "nlohmann/json 可用" << std::endl;
#else
std::cout << "nlohmann/json 不可用" << std::endl;
#endif
#ifdef HAS_FMT
std::cout << "fmt 库可用" << std::endl;
#else
std::cout << "fmt 库不可用" << std::endl;
#endif
return 0;
}// ============================
// 示例5:配合特性测试宏使用
// ============================
// C++20 引入了 <version> 头文件,包含所有特性测试宏
// 但在 C++17 中可以用 __has_include 检测它是否存在
#ifdef __has_include
# if __has_include(<version>)
# include <version>
# endif
#endif
#include <iostream>
int main() {
// 检查各种 C++17/20 特性的支持情况
#ifdef __cpp_lib_optional
std::cout << "optional 支持,版本: " << __cpp_lib_optional << std::endl;
#endif
#ifdef __cpp_lib_filesystem
std::cout << "filesystem 支持,版本: " << __cpp_lib_filesystem << std::endl;
#endif
#ifdef __cpp_lib_ranges
std::cout << "ranges 支持,版本: " << __cpp_lib_ranges << std::endl;
#else
std::cout << "ranges 不支持" << std::endl;
#endif
return 0;
}__has_include 与其他特性检测方式的对比
| 方式 | 检测时机 | 可移植性 | 需要构建系统 | 粒度 |
|---|---|---|---|---|
__has_include(C++17) | 预处理期 | C++17 编译器 | 不需要 | 头文件级别 |
CMake check_include_file | 构建配置期 | 高 | 需要 CMake | 头文件级别 |
平台宏(_WIN32、__linux__) | 预处理期 | 不同编译器不同 | 不需要 | 平台级别 |
特性测试宏(__cpp_lib_xxx) | 预处理期 | C++20 标准化 | 不需要 | 特性级别 |
__has_cpp_attribute | 预处理期 | C++17 | 不需要 | 属性级别 |
适用场景
- 在代码中自动适配不同版本的标准库(标准版 vs 实验版)
- 检测第三方库是否安装,自动选择实现
- 跨平台代码中检测平台特定头文件
- 库开发者提供对不同编译器/标准版本的透明支持
- 配合
<version>头文件检测具体特性的支持情况
常见问题
__has_include 能检测头文件的内容吗?
不能。它只检测头文件是否"能被找到"(即 #include 是否会成功),不检查头文件内包含了什么。即使头文件存在但内容为空或有错误,__has_include 仍然返回 1。
__has_include 能在普通 C++ 代码中使用吗?
不能。它只能在预处理指令(#if、#elif)中使用。不能写 if (__has_include(<optional>)) 这样的代码。
__has_include 检测到头文件存在,但 include 后编译报错怎么办?
__has_include 只保证头文件能被找到,不保证头文件中的功能在当前编译模式下可用。比如 <filesystem> 头文件可能存在,但如果没有开启 C++17 模式(-std=c++17),里面的功能可能不可用。建议配合特性测试宏(__cpp_lib_filesystem)一起使用。
旧编译器不支持 __has_include 怎么办?
用 #ifdef __has_include 先检查它是否可用。如果不可用,就回退到传统的平台检测或构建系统配置。
注意事项
__has_include只在#if/#elif预处理指令中有效- 它检查的是头文件是否能被找到,不验证内容
- 使用前最好用
#ifdef __has_include检查可用性,保证对旧编译器的兼容 __has_include不能替代所有特性检测——头文件存在不等于特性可用- 在
#if defined(__has_include)和#ifdef __has_include的效果相同 __has_include的宏名字以双下划线开头,属于实现保留的标识符空间
编译器支持情况
| 编译器 | 最低支持版本 |
|---|---|
| GCC | 5.0 |
| Clang | 所有版本(早期作为扩展,C++17 标准化) |
| MSVC | 19.11 (VS 2017 15.3) |
总结
__has_include 是 C++17 标准化的预处理器特性,用来在编译前检测头文件是否可用。它最常见的用法是在标准库的标准版和实验版之间自动选择、检测第三方库是否安装、以及检测平台特定的头文件。和传统的构建系统配置相比,它的优势是直接在源代码中完成检测,不需要额外的构建步骤。但它只检查头文件是否存在,不验证头文件中的功能是否可用——对于更精细的特性检测,应该配合 C++20 的 <version> 头文件和特性测试宏(__cpp_lib_xxx)一起使用。