pragma once非标准且存在兼容性、缓存及路径识别问题，需与#ifndef卫士宏共用；卫士宏须用唯一稳定宏名并严格配对，二者混合是分层防御而非冗余。
为什么 #pragma once 不是万能的
它确实能防止头文件被同一编译单元重复包含，但只在单个 .cpp 文件内生效。跨文件、跨编译单元时，每个 .cpp 各自处理自己的 #pragma once，这本身没问题；问题出在构建系统或 IDE 缓存异常时——比如修改了头文件却没触发重编译，#pragma once 就不会重新检查路径一致性。
更关键的是：它不是 C++ 标准特性，而是编译器扩展。主流编译器（Clang、GCC 5.1+、MSVC）都支持，但某些嵌入式工具链或老版本 GCC（如 4.8）可能不识别，直接忽略且不报错，导致静默重复定义。
- 用
#pragma once前先确认构建环境中的编译器版本和目标平台支持情况 - 若需严格可移植（比如开源库要兼容 GCC 4.4），必须搭配传统卫士宏（
#ifndef XXX_H） - IDE 有时会基于
#pragma once做头文件跳转或索引，但若路径存在软链接或挂载差异，可能误判为不同文件——此时卫士宏更可靠
#ifndef 卫士宏怎么写才不出错
常见错误是宏名和文件名不一致，或者用了易冲突的简短名（比如 UTIL_H），结果多个头文件撞名，一个被跳过，另一个实际没生效。
正确做法是生成唯一、稳定、可读的宏名，推荐用全路径哈希或规范化大写路径（去掉点、斜杠转下划线）。例如 src_core_math_vector_h 比 VECTOR_H 安全得多。
立即学习“C++免费学习笔记（深入）”；
- 宏名中避免出现
.、-、/等非法字符，全部转成_ - 不要依赖
__FILE__或__LINE__生成宏名——预处理器不展开它们做宏判断 - 卫士宏必须严格配对：
#ifndef→#define→#endif，中间不能有前置#ifdef或条件跳过 - 宏定义行末不要加
;，否则可能干扰后续代码解析（尤其在宏拼接场景）
混合使用 #pragma once 和卫士宏是否多余
不少项目两者并存，不是冗余，而是分层防御：前者给现代编译器提速（跳过文件内容扫描），后者兜底保兼容性和语义确定性。
GCC 在开启 -Winvalid-pch 或预编译头时，对 #pragma once 的处理逻辑和普通宏略有差异；而 MSVC 对卫士宏的宏展开顺序更严格。两者共存时，只要顺序合理（#pragma once 放最顶，卫士宏紧随其后），编译器会优先走 #pragma once 快路径，失败时再 fallback 到宏判断。
- 推荐写法：
#pragma once #ifndef SRC_CORE_LOG_H #define SRC_CORE_LOG_H // 头文件正文 #endif
- 不要把
#pragma once写在卫士宏中间或之后，部分旧版 Clang 会忽略 - CI 构建中若用不同编译器交叉验证，混合写法能提前暴露不兼容隐患
头文件重复包含的真实危害不止于编译错误
表面看只是 redefinition 报错，但深层影响更隐蔽：模板实例化爆炸、内联函数多重定义（ODR 违反）、静态变量重复初始化、调试符号混乱——这些在优化开启（-O2）后才浮现，且难以复现。
尤其当头文件里含 static_assert、constexpr 变量或 inline 函数时，重复包含会导致断言多次触发或符号地址不一致，GDB 调试时看到的行号和实际执行流对不上。
- 用
g++ -H your_file.cpp查看头文件包含树，确认是否有意外重复路径 - CMake 中可通过
target_include_directories(... PRIVATE)控制可见性，比无脑include_directories()更安全 - 注意 C++20 模块（
import）不解决头文件问题，它完全绕过预处理器——迁移前得先理清现有头文件依赖闭环
真正麻烦的从来不是“怎么防”，而是“哪次没防住”——那个漏掉的头文件，往往藏在第三方子模块的私有 #include 里，等你改完主逻辑才发现链接阶段炸了。
