__has_include 预处理指令 ​

什么是 __has_include ​

__has_include 是 C++17 标准化的一个预处理器特性,用来在编译前检测某个头文件是否可用。它在 #if / #elif 预处理指令中使用,如果指定的头文件存在(能被编译器找到),表达式求值为 1;否则求值为 0。

在 C++17 之前,想知道某个头文件是否存在,只能靠构建系统(CMake 的 check_include_file)或平台/编译器宏来间接判断。__has_include 让这件事变得简单直接——在源代码中就能完成,不依赖外部构建配置。

这个特性在 Clang 中早已作为编译器扩展存在多年,C++17 将其正式纳入标准。

语法 ​

cpp
// 检查系统头文件(用尖括号)
#if __has_include(<header_name>)

// 检查本地头文件(用双引号)
#if __has_include("header_name")

它只能出现在 #if、#elif 等预处理条件表达式中,不能在普通 C++ 代码中使用。

为了兼容不支持 __has_include 的旧编译器,通常先检查 __has_include 本身是否可用:

cpp
#ifdef __has_include
#  if __has_include(<optional>)
#    include <optional>
#  endif
#endif

基本示例 ​

cpp
// ============================
// 示例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;
}
cpp
// ============================
// 示例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;
}
cpp
// ============================
// 示例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;
}
cpp
// ============================
// 示例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;
}
cpp
// ============================
// 示例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 的宏名字以双下划线开头,属于实现保留的标识符空间

编译器支持情况 ​

编译器最低支持版本
GCC5.0
Clang所有版本(早期作为扩展,C++17 标准化)
MSVC19.11 (VS 2017 15.3)

总结 ​

__has_include 是 C++17 标准化的预处理器特性,用来在编译前检测头文件是否可用。它最常见的用法是在标准库的标准版和实验版之间自动选择、检测第三方库是否安装、以及检测平台特定的头文件。和传统的构建系统配置相比,它的优势是直接在源代码中完成检测,不需要额外的构建步骤。但它只检查头文件是否存在,不验证头文件中的功能是否可用——对于更精细的特性检测,应该配合 C++20 的 <version> 头文件和特性测试宏(__cpp_lib_xxx)一起使用。