应优先使用 #ifndef / #define / #endif，因其是标准、可移植、可靠；#pragma once 虽简洁但非标准，存在文件系统依赖和兼容性风险。

用 #ifndef 或 #pragma once 都能防止头文件重复包含，但它们机制不同、兼容性不同、行为边界也不同——选错可能在跨平台或大型项目中埋坑。

为什么重复包含头文件会出问题

多次包含同一头文件，会导致符号重定义（比如类重复声明、函数重复声明）、模板实例化冲突、编译变慢。C++ 标准不保证头文件被多次包含时的行为安全，必须主动防护。

常见触发场景：

• 多个头文件都 #include "common.h"，而它们又被同一个 .cpp 同时包含
• 继承链中间接包含同一头文件（A.h → B.h → C.h，同时 A.h → C.h）

#ifndef / #define / #endif 是标准、可控、可移植的方案

它依赖宏名唯一性，由预处理器在文本层面判断是否跳过内容。只要宏名不冲突，就可靠。

立即学习“C++免费学习笔记（深入）”；

典型写法（注意命名规范）：

笔尖Ai写作

AI智能写作，1000+写作模板，轻松原创，拒绝写作焦虑！一款在线Ai写作生成器

下载

#ifndef MYLIB_VECTOR_H_
#define MYLIB_VECTOR_H_
include 
namespace mylib {
template class vector { / ... / };
} // namespace mylib
endif // MYLIB_VECTORH

关键点：

• 宏名建议用 大写 + 下划线 + 文件路径信息（如 UTILS_LOG_H_），避免和用户代码/第三方库冲突
• 必须成对出现：#ifndef 和 #endif 之间不能有未配对的条件编译指令
• 支持所有符合标准的预处理器（GCC、Clang、MSVC、ICC 等），无兼容性风险
• 即使头文件被 #include <...> 和 #include "..." 同时引用，也能正确识别为同一文件（靠路径字符串匹配）

#pragma once 是编译器扩展，简洁但有隐含限制

它让编译器直接按物理文件路径做去重，不依赖宏名，写起来更轻量：

#pragma once
include 
namespace mylib {
template class vector { / ... / };
}

但它的问题藏在细节里：

• 不是 C++ 标准特性，虽被 GCC/Clang/MSVC 广泛支持，但某些嵌入式工具链或老版本编译器（如早期 TI C++ 编译器）可能不识别
• 对硬链接、符号链接、网络文件系统（NFS）、生成头文件（如通过 CMake configure_file 生成）等场景识别不稳定——同一逻辑头文件若路径不同，#pragma once 可能认为是两个文件
• 无法处理“不同路径指向同一文件”的情况（例如 /src/a.h 和 /build/src/a.h 是硬链接），而 #ifndef 因宏名相同仍能生效
• 宏名冲突的风险被规避了，但换来的是对文件系统语义的强依赖

实际项目中怎么选

没有绝对优劣，只有上下文适配：

• 开源库、跨平台 SDK、需长期维护的底层模块：优先用 #ifndef，确保可预测性和最大兼容性
• 公司内部 MSVC/Clang 主导的项目，且构建环境统一、无符号链接/NFS：可用 #pragma once 提高可读性，但需在 CI 中验证所有目标平台
• 混合使用？不推荐。同一项目中混用会让新人困惑，且 IDE 的头文件导航、静态分析工具可能表现不一致
• 现代建议：用 #pragma once + 保留 #ifndef 注释作为兜底（非强制，仅提醒），但不要真写两套防护

真正容易被忽略的是：头文件防护只是第一道防线；如果头文件本身有定义非内联函数、全局变量或模板以外的实体，还需配合 inline、static、extern 或定义分离（声明放头文件，定义放 .cpp）来避免 ODR 违规——防护宏管不了链接期错误。