pragma once 有时失效，因其依赖编译器通过绝对路径或 inode 识别文件物理身份；在符号链接、硬链接、wsl/docker 路径映射或 nfs 挂载等场景下，同一文件可能被视作多个实例，导致重复包含；而 #ifndef 依赖唯一宏名，不受路径影响，更可靠。
为什么#pragma once有时会失效
它依赖编译器对文件物理身份的识别，比如绝对路径或 inode。当项目中存在符号链接、硬链接，或者头文件通过不同挂载路径（如 Docker 容器内外、Windows WSL 路径映射）被引用时，#pragma once 可能将同一份内容视为“两个文件”，从而重复包含。
这不是 bug，而是设计使然——它守的是“文件实例”，不是“文件内容”。而 #ifndef 守的是宏名，只要宏名唯一，哪怕文件被软链接多次引入，也只生效一次。
- 常见错误现象：
error: redefinition of 'class X'，但检查发现只#include "x.h"了一次 - 排查方法：用
g++ -E main.cpp | grep "x.h"看预处理后是否真出现了两次内容 - 嵌入式或 CI 环境中尤其要注意 NFS、CIFS 或 Git LFS 挂载导致的路径不一致
#ifndef HEADER_H 的命名冲突怎么避不开
宏名必须全局唯一，但没人强制你写 PROJECT_MODULE_SUBMODULE_FEATURE_H 这种长名。实际项目里，CONFIG_H、COMMON_H、UTILS_H 这类短名极易撞车——尤其当你集成第三方库或子模块时。
一旦两个头文件都用了 #ifndef UTILS_H，后包含的那个会被静默跳过，编译器不会报错，但可能突然找不到声明、类型不匹配、模板特化失效，调试起来非常隐蔽。
- 使用场景：开源库、跨团队协作、历史代码迁移时风险最高
- 参数差异：
#ifndef本身无参数，但宏名是隐式“参数”，需人工保证不重复 - 建议：用
__开头 + 项目/目录路径哈希（如__MYPROJ_SRC_UTILS_H），避免裸名
编译速度差多少？真的值得换
在大型项目（>1000 个头文件）中，#pragma once 平均快 3%~8%，主要省在跳过 I/O 和预处理扫描上。但它只在首次包含该文件时生效；后续包含仍要走 #include 解析流程，只是内容被跳过。
#ifndef 则每次都要打开文件、扫描到 #endif 才决定跳过，I/O 和文本扫描开销更实在。不过现代编译器（Clang/GCC）已对 include guard 做了优化，差距比十年前小得多。
- 性能影响只在增量编译或头文件频繁变更时明显
- 不要为这点速度放弃可移植性——除非你明确锁定 MSVC/Clang 且构建系统可控
- 混合写法
#pragma once\n#ifndef FOO_H\n#define FOO_H不提升性能，反而增加维护负担
混用#pragma once和#ifndef安全吗
语法上完全合法，也能“双重保险”，但没实际增益。如果 #pragma once 生效了，#ifndef 根本不会被检查；如果它失效（比如 symlink 场景），#ifndef 仍起作用——所以它只是 fallback，不是叠加防护。
真正的问题在于：混用会让新成员误以为“两个都写才规范”，结果复制粘贴时漏删一个，或改名时只改了宏不改 #pragma once，造成逻辑割裂。
- 容易踩的坑：Git 合并冲突时，可能留下残缺的守卫块，比如只有
#pragma once没有#ifndef，或反之 - CI 流水线若跑在不同 OS 上（Linux/macOS/Windows），混用反而暴露兼容性盲区
- 最易被忽略的一点：IDE 的“跳转到定义”或“重命名符号”功能，通常只认宏名，不认
#pragma once，混用会干扰工具链
C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
