C++ 中 __has_include 宏：安全检测头文件存在性的标准方案

在跨平台、多版本编译器和复杂依赖环境下，C++ 项目常面临一个基础却关键的问题：如何在预处理阶段判断某个头文件是否可用？例如，某功能在较新标准库中提供（如 <span>），但旧版编译器或裁剪版 STL 并未包含；又或需根据系统是否支持 <sys/epoll.h> 来启用特定 I/O 机制。传统做法如 #include <header.h> 后捕获编译错误，不仅破坏构建健壮性，也无法实现条件编译逻辑。自 C++17 起，标准化的 __has_include 预处理运算符为此类需求提供了简洁、可靠且可移植的解决方案。

__has_include 并非函数，而是一个编译器内置的预处理运算符，其语法形如 __has_include("header") 或 __has_include(<header>)。它在预处理阶段求值，返回整型常量 1（头文件存在且可被 #include）或 0（不存在、不可访问或路径非法）。该运算符不触发实际包含动作，仅做存在性探查，因此完全无副作用，也不会引入额外依赖或宏污染。

值得注意的是，__has_include 的行为严格遵循 #include 的查找规则：双引号形式 "header" 按本地路径优先搜索（当前目录、-I 指定路径等），尖括号形式 <header> 则按系统路径优先搜索（如 /usr/include）。二者语义与常规 #include 一致，确保检测结果与后续实际包含行为保持同步。

以下是最典型的使用模式——通过 #if 结合 __has_include 实现头文件感知的条件编译：

// 检测标准库头文件是否存在
#if __has_include(<optional>)
#  include <optional>
#  define HAS_STD_optionAL 1
#else
#  define HAS_STD_OPTIONAL 0
#endif

#if __has_include(<filesystem>)
#  include <filesystem>
#  define HAS_STD_FILESYSTEM 1
#else
#  define HAS_STD_FILESYSTEM 0
#endif

// 使用示例：仅当 optional 可用时定义包装类型
#if HAS_STD_OPTIONAL
using maybe_int = std::optional<int>;
#else
// 提供轻量级回退实现（此处仅为示意）
struct maybe_int {
    int value;
    bool has_value{false};
};
#endif

该模式将“探测”与“使用”解耦：先统一检测并定义宏标志，再在后续代码中依据标志选择实现路径。这种结构清晰、易于维护，也便于单元测试覆盖不同配置分支。

对于第三方或系统头文件，__has_include 同样适用。例如，在 Linux 环境下安全启用 epoll 支持，同时兼容 BSD 的 kqueue 或通用 poll：

// 检测系统 I/O 多路复用接口
#if __has_include(<sys/epoll.h>)
#  include <sys/epoll.h>
#  define IO_BACKEND "epoll"
#elif __has_include(<sys/kqueue.h>)
#  include <sys/kqueue.h>
#  define IO_BACKEND "kqueue"
#else
#  include <poll.h>
#  define IO_BACKEND "poll"
#endif

// 编译期断言确保至少一种后端可用
static_assert(__has_include(<sys/epoll.h>) ||
              __has_include(<sys/kqueue.h>) ||
              __has_include(<poll.h>),
              "No I/O multiplexing header available");

此处 static_assert 在编译期验证至少一个头文件存在，避免静默降级导致运行时错误，进一步强化了健壮性。

需要强调几个关键约束与最佳实践。首先，__has_include 是 C++17 标准特性，但主流编译器（GCC 5+、Clang 3.9+、MSVC 2017 15.3+）均早已支持。若需兼容更老编译器，可结合 __cplusplus 宏进行降级处理：

#if __cplusplus >= 201703L && defined(__has_include)
#  if __has_include(<string_view>)
#    include <string_view>
#    define HAS_string_VIEW 1
#  else
#    define HAS_STRING_VIEW 0
#  endif
#else
#  define HAS_STRING_VIEW 0
#endif

其次，__has_include 仅检测头文件是否“存在”，不保证其内容符合预期。例如，某头文件可能存在但声明不全，或版本过低。此时应配合其他特征检测（如 __has_cpp_attribute、宏定义检查）形成组合策略。

最后，避免在 __has_include 参数中使用宏展开——其参数必须为字面字符串或尖括号内字面标识符，宏不会被展开。如下写法是错误的：

// 错误：宏 HEADER_NAME 不会被展开
#define HEADER_NAME <vector>
#if __has_include(HEADER_NAME)  // 预处理器报错：期望字符串或尖括号

正确方式是直接使用字面量，或借助中间宏（需谨慎）：

// 正确：直接字面量
#if __has_include(<vector>)

// 若需动态生成，须用两层宏技巧（不推荐，降低可读性）
#define INCLUDE_STR(x) #x
#define HAS_INCLUDE(x) __has_include(INCLUDE_STR(x))
#if HAS_INCLUDE(vector)  // 展开为 __has_include("vector")

综上，__has_include 是现代 C++ 工程化开发中不可或缺的基础设施。它以极简语法解决了长期困扰跨平台项目的头文件可移植性难题，使代码能优雅地适应不同工具链、标准库版本及操作系统环境。合理运用该特性，不仅能提升构建稳定性，更能推动接口设计向“渐进增强”演进——在能力可用时启用高级特性，否则平稳回退至兼容实现。对于追求高质量、高可维护性的 C++ 项目而言，掌握并规范使用 __has_include，已成为一项基础而重要的工程素养。