pragma once 不能完全替代 #include 守卫宏，因其是非标准编译器扩展，旧版 GCC 等编译器可能不支持，且在符号链接、多路径包含等场景下失效；而 #ifndef 守卫符合标准、跨平台可靠，能处理内容相同但路径不同的重复包含。
为什么 #pragma once 不能完全替代 #include 守卫宏
因为 #pragma once 是编译器扩展，不是 C++ 标准语法。虽然主流编译器（MSVC、Clang、GCC 14+）都支持，但旧版 GCC（
实际项目中更稳妥的做法是「两者共存」：用 #pragma once 做快速判断，再用传统宏守卫兜底。这样既享受其简洁性，又保留标准兼容性。
-
#pragma once依赖文件路径的唯一性识别，若同一头文件通过不同路径（如软链接、符号路径、-I 多级包含）被引入，可能失效 - 宏守卫（如
#ifndef MY_HEADER_H）靠预处理器符号，不受路径影响，但需人工保证宏名不冲突 - 现代 CMake/IDE 通常能自动生成守卫宏名，但手写时建议用
PROJECTNAME_MODULENAME_H_INCLUDED格式，避免简单拼写如UTIL_H
#pragma once 放在头文件什么位置才有效
必须放在头文件最开头，且前面只能有注释、空行和 #if/#ifdef 等条件编译指令（不能有任何 #include 或代码）。一旦预处理器读到 #pragma once，就会记录该文件路径；后续再次遇到相同路径就跳过整个文件内容。
错误示例：#include <string> 写在 #pragma once 前面，会导致该 #include 被执行两次（第一次正常，第二次因 pragma 生效被跳过，但前置依赖已污染全局状态）。
立即学习“C++免费学习笔记（深入）”；
组合式C++代码评审方案，融合静态分析、AI推理、多轮迭代评审和C++专项检查，适用于PR审查、增量代码审查、全项目评审和代码质量评分，触发词包括review cpp、cpp代码评审、C++review、代码审查。
- 正确顺序：
// 注释→#pragma once→#include→ 其他内容 - 不要在
.cpp文件里写#pragma once—— 它只对头文件有意义 - 如果头文件内有
#if defined(__GNUC__) && __GNUC__ 这类判断，<code>#pragma once必须放在这类条件块外面，否则可能被跳过
哪些情况会让 #pragma once 失效或行为异常
最常见的是构建系统引入同一物理文件的多个逻辑路径。比如源码树中有 src/core/log.h，而构建目录通过 -I build/include 和 -I src/ 同时暴露了 build/include/log.h（软链接到原文件）和 src/core/log.h。这时编译器认为这是两个不同路径，#pragma once 会分别处理。
- Windows 下大小写不敏感 + 路径分隔符混用（
\vs/）也可能触发误判 - 使用 CMake 的
target_include_directories(... PRIVATE)时，若多个 target 指向同一头文件但 include 路径不同，容易暴露该问题 - CI 环境中挂载路径与本地开发路径不一致（如 Docker volume 映射），也会让
#pragma once的路径指纹失效
这类问题很难复现，但一旦发生，症状是模板定义重复、static 变量多份实例、inline 函数 ODR 违反等链接期错误，排查成本很高。
要不要在所有头文件里无脑加 #pragma once
可以加，但别指望它解决一切。它只是第一道轻量级防线，真正的防御主力仍是宏守卫。尤其对于公开头文件（SDK、库接口）、跨平台项目、或需要被 Doxygen/C++ Insights 等工具解析的场景，必须保留标准守卫宏。
- 内部模块头文件可单独用
#pragma once，前提是团队统一工具链且 CI 覆盖足够 - 若项目已用 CMake 的
set_property(SOURCE xxx.h PROPERTY LANGUAGE CXX)控制头文件属性，#pragma once的作用会被进一步弱化 - 注意 IDE 自动补全有时会插入错误格式的
#pragma once（比如缩进后或带多余空格），某些旧编译器会直接忽略
真正麻烦的从来不是加不加这一行，而是当 #pragma once 和宏守卫不一致时（比如宏名拼错但 pragma 正常生效），你会得到一个看似没报错、实则部分声明缺失的静默坏构建。
