头文件多次包含会违反ODR原则导致重定义错误；应使用#ifndef/define/endif宏卫士（推荐PROJECTNAME_SUBDIR_FILENAME_H格式）或#pragma once，二者可共存以兼顾兼容性与简洁性。
为什么 #include 多次会导致编译失败
头文件被多次包含时，编译器会反复看到相同的类型定义、函数声明或全局变量声明，比如重复的 struct Foo 或 extern int g_value;。C++ 标准禁止同一翻译单元内多次定义同一实体（ODR 原则），所以会报错：error: redefinition of 'XXX' 或 error: 'XXX' has already been declared in this scope。
常见诱因：你自己 #include "a.h"，而 a.h 内部又 #include "b.h"，但主文件也直接写了 #include "b.h"；或者多个头文件都依赖同一个公共头（如 common.h），没做防护。
- 不是所有头文件都“天然安全”——即使只含声明，
inline函数、模板特化、constexpr变量等仍可能触发 ODR 违规 -
#pragma once能解决大部分问题，但它不是 C++ 标准特性，极少数旧编译器（如某些嵌入式工具链）不支持 - 标准做法仍是
#ifndef/#define/#endif宏卫士，兼容性最稳
怎么写可靠的头文件卫士宏
核心是用一个**全局唯一、不易冲突**的宏名包裹整个头文件内容。不能简单用 FOO_H，因为项目大了容易重名；也不能用随机字符串，维护困难。
- 推荐格式：
PROJECTNAME_SUBDIR_FILENAME_H，全大写 + 下划线，例如MYLIB_UTILS_STRINGUTILS_H - 宏名里避免只用文件名（如
STRINGUTILS_H），不同目录下同名头文件会冲突 - 不要手动拼写宏名——用编辑器宏或脚本生成，或直接复制粘贴已有模板，减少手误
- 宏定义必须放在头文件**最开头**，且紧贴
#ifndef后面，中间不能有空行或注释（某些老预处理器对此敏感）
正确示例：
立即学习“C++免费学习笔记（深入）”；
C++ Code Review Master
下载
组合式C++代码评审方案，融合静态分析、AI推理、多轮迭代评审和C++专项检查，适用于PR审查、增量代码审查、全项目评审和代码质量评分，触发词包括review cpp、cpp代码评审、C++review、代码审查。
#ifndef MYLIB_UTILS_STRINGUTILS_H
#define MYLIB_UTILS_STRINGUTILS_H
#include <string>
namespace mylib {
std::string trim(const std::string& s);
} // namespace mylib
#endif // MYLIB_UTILS_STRINGUTILS_H
#pragma once 能不能替代宏卫士
绝大多数现代编译器（GCC 3.4+、Clang、MSVC）都支持 #pragma once，它语义更清晰、书写更短，且能避免宏名冲突问题。
- 但它依赖编译器识别“同一文件”，如果通过符号链接、硬链接或网络路径访问同一物理文件，部分旧版本 GCC 可能误判为不同文件，导致卫士失效
- 在构建系统中使用自动生成头文件（如由 CMake configure_file 生成），若路径不稳定，
#pragma once可能漏防 - 混合使用时注意：如果一个头同时有
#pragma once和宏卫士，后者仍需保留——有些静态分析工具或预处理器只认宏
务实建议：新项目可优先用 #pragma once，但团队里若有嵌入式或超旧工具链需求，必须补上宏卫士；二者共存不冲突，只是多一行。
哪些情况宏卫士会失效
宏卫士只防“同一头文件多次包含”，对其他重复问题无能为力。
- 不同头文件定义了相同名字的
inline函数（未加static或匿名命名空间）——宏卫士挡不住，链接时报multiple definition - 头文件里写了非
extern的全局变量定义（如int counter = 0;），即使加了卫士，每个包含它的 .cpp 都会生成一份定义 - 模板显式特化写在头文件里，但没用
extern template声明控制实例化位置，可能导致多个 TU 生成相同特化代码 - 用
#include <xxx>包含系统头时，别自己给它加卫士——系统头已自带，强行加反而可能破坏其内部逻辑
真正难防的是语义重复，不是文本重复。卫士只是第一道门，类型设计和链接规则才是深层防线。
