头文件重复包含会导致编译失败，因预处理后出现重复声明（如类、函数），触发编译期重定义错误；解决方法为条件编译守卫：#ifndef/#define/#endif（需全局唯一宏名）或非标准但简洁的#pragma once。
为什么头文件重复包含会导致编译失败
头文件被多次 #include 时，若其中定义了类、函数声明、宏或内联函数，会触发重复定义错误（如 error: redefinition of 'class X' 或 multiple definition of 'foo()'）。这不是链接期问题，而是预处理后源文件中出现了两份相同声明，编译器直接报错。
解决思路只有两个：让预处理器跳过第二次及之后的包含。核心手段就是条件编译守卫（include guard）——要么用 #ifndef/#define/#endif 手写，要么用编译器扩展 #pragma once。
#ifndef 守卫怎么写才安全
手动守卫的关键是宏名必须全局唯一，否则不同头文件用了相同宏名，会导致其中一个被静默跳过。
- 推荐用「文件路径大写 + 下划线」规则，例如
UTILS_STRING_UTILS_H对应utils/string_utils.h - 避免只用简单名字如
STRING_H，极易冲突 - 宏名末尾加
_H或_HH是常见约定，但不是强制，重点是唯一性 - 守卫必须包裹整个头文件内容，包括
#include指令本身（否则嵌套包含失效）
正确示例：
立即学习“C++免费学习笔记（深入）”；
#ifndef CORE_MATH_VECTOR2_H #define CORE_MATH_VECTOR2_H #includestruct Vector2 { float x, y; Vector2 operator+(const Vector2& o) const; }; #endif // CORE_MATH_VECTOR2_H
#pragma once 的实际兼容性与风险
#pragma once 语义更简洁：只要该物理文件已被包含过一次，后续 #include 就直接跳过。但它不是 C++ 标准，而是编译器扩展。
- 主流编译器（GCC 3.4+、Clang、MSVC）都支持，且行为一致
- 不依赖宏名，天然规避命名冲突问题
- 但遇到硬链接、符号链接、网络文件系统（NFS）挂载或同一文件有多个路径可访问时，部分旧版编译器可能误判为“不同文件”，导致守卫失效
- 某些构建系统（如基于路径哈希的增量编译工具）可能无法正确识别
#pragma once的依赖关系
所以它快、干净、够用，但在高可靠性或跨平台嵌入式环境中，仍建议优先用 #ifndef 守卫。
能不能混用？或者用双重守卫？
可以，而且有人这么做，但没必要。双重守卫（#pragma once + #ifndef）不会出错，但增加冗余，且没带来实质收益。
-
#pragma once被忽略时，#ifndef仍生效 —— 所以它只是“多一层保险” - 但现代编译器下这层保险几乎从不触发，反而让代码显得不自信
- 更严重的是：如果
#ifndef宏名写错了（比如漏了下划线），而你又依赖#pragma once，那在不支持它的编译器上就彻底崩了 - 统一选一种，并确保团队共识和 CI 检查（比如用 clang-tidy 的
cppcoreguidelines-avoid-macro-use配合自定义检查）
真正容易被忽略的点是：模板定义、内联函数、constexpr 变量这些本该放在头文件里的东西，一旦没加守卫，错误会出现在链接阶段（ODR violation），而不是编译期，排查起来更隐蔽。
