推荐优先使用#ifndef而非#pragma once，因其符合C/C++标准、可移植性强且能可靠处理硬链接等边界情况；#pragma once虽快但非标准，仅宜作为辅助手段。
#pragma once 和 #ifndef 都是用来防止头文件被重复包含的机制，但原理、兼容性和可靠性完全不同。在工程实践中，推荐优先使用 #ifndef（即 include guard），#pragma once 仅作为辅助或团队约定下的补充手段。
原理差异：编译器行为 vs 预处理器逻辑
#pragma once 是编译器指令，由编译器在打开文件时检查该文件是否已被包含过。它依赖编译器对“同一文件”的判断（通常基于文件路径或 inode），不经过预处理器，速度快，写法简洁。
#ifndef 是标准 C/C++ 预处理器机制：通过定义唯一宏名，配合 #ifndef / #define / #endif 三行代码实现逻辑保护。它不关心文件路径，只看宏是否已定义，完全符合语言标准，可移植性极强。
兼容性与可靠性：关键工程考量
- #pragma once 不是 C/C++ 标准的一部分，虽被主流编译器（MSVC、GCC 5.0+、Clang）支持，但在某些嵌入式工具链、老版本编译器（如早期 GCC 4.x）或静态分析工具中可能被忽略或误判；
- 当存在硬链接、符号链接、网络文件系统挂载、或不同路径指向同一物理文件时，#pragma once 可能失效（例如
/src/a.h和/build/include/a.h实为同一文件，但编译器视为两个文件）； - #ifndef 完全规避上述问题：只要宏名唯一且作用域正确，无论文件如何链接、复制或映射，都能可靠工作；
- 部分构建系统（如某些 CMake + Ninja 组合）或头文件生成流程中，#pragma once 可能干扰依赖自动推导，而 #ifndef 总是被准确识别。
工程实践建议：怎么用才稳妥？
-
默认坚持用 #ifndef：所有对外发布、跨平台、长期维护的项目，头文件起始必须有规范 include guard，宏名建议用
PROJECT_MODULE_FILENAME_H格式（如MYLIB_UTILS_STRING_H），避免下划线开头（保留给实现）； - 可同时写 #pragma once + #ifndef：现代编译器会优先识别 #pragma once 加速处理，预处理器兜底保证正确性——这是一种“兼顾效率与安全”的常见折中；
- 禁止单独依赖 #pragma once，尤其在 SDK、中间件、开源库中；
- CI/CD 流程中建议用
-Wheader-guard（Clang）或自定义脚本检查 include guard 缺失或命名冲突，不检查 #pragma once 是否存在。
一个小例子：推荐写法
✅ 好的头文件开头：
立即学习“C++免费学习笔记（深入）”；
#pragma once #ifndef MYAPP_CORE_LOG_H #define MYAPP_CORE_LOG_H #includenamespace myapp { void log_info(const std::string& msg); } // namespace myapp #endif // MYAPP_CORE_LOG_H
这样既享受了 #pragma once 的解析速度，又保留了 #ifndef 的标准保障，是工业级项目的主流选择。
