pragma once 更简洁、无宏名冲突风险，主流编译器已完全支持；仅在条件编译和文档生成等边缘场景需保留 include guard。
因为 #pragma once 更简洁、不易出错，且主流编译器（GCC 13+、Clang、MSVC）已完全支持，实际项目中几乎无兼容性风险。
为什么 #pragma once 不会像 include guard 那样误定义宏
include guard 依赖手动命名的宏（如 MY_HEADER_H），一旦两个头文件用了相同宏名，就会导致后者被静默跳过——这种错误不报错、难调试。而 #pragma once 由编译器根据文件路径（而非宏名）判定是否已包含，天然规避宏名冲突。
常见错误现象：
- 修改了
utils.h，但main.cpp没生效 → 实际是另一个同名utils.h（比如子模块里）触发了重复的UTILS_H宏 - 头文件被硬链接或符号链接引用 → include guard 可能失效（不同路径被视为不同文件），而
#pragma once在多数编译器中能正确识别同一文件实体
#pragma once 在跨平台构建中的真实兼容性
过去担心它“非标准”，但现在：gcc 自 13.1 起默认启用；clang 从 2.0 就支持；MSVC 支持超 20 年。C++20 标准虽未纳入，但 ISO/IEC TS 24780:2021 已将其列为“广泛接受的扩展”。
立即学习“C++免费学习笔记（深入）”；
唯一需注意的场景：
- 极老的嵌入式工具链（如某些基于 GCC 4.9 的 ARM bare-metal 工具链）→ 查
gcc -v输出，确认是否含#pragma once支持字样 - 使用
ccache且未配置ccache --set-config=direct_mode=true→ 旧版 ccache 可能因文件 inode 判断异常跳过缓存，但这是 ccache 配置问题，不是#pragma once本身缺陷
include guard 还有什么不可替代的用途？
绝大多数情况不需要。仅在两种边缘场景仍需保留 include guard（或二者共存）：
- 需要条件性禁用头文件包含逻辑，例如：
#ifndef DISABLE_LEGACY_API #include "legacy.h" #endif
—— 这类控制必须靠宏，#pragma once无法参与预处理条件判断 - 生成文档时依赖宏名提取接口（如 Doxygen 的
@file解析），部分旧脚本可能只认HEADER_H这类宏作为文件标识
真正容易被忽略的是：#pragma once 对 symlink 和 hardlink 的行为依赖编译器实现。GCC 和 Clang 默认按 real path 判重，但若用 -frecord-gcc-switches 或某些自定义构建系统绕过文件系统缓存，可能意外失效。这时候不是换回 include guard，而是检查构建环境是否一致地解析了文件路径。
