头文件重复包含是指同一头文件被多次#include导致预处理阶段重定义错误；可用#pragma once或传统宏守卫（#ifndef/#define/#endif）防止，二者可共存且#pragma once需置于守卫之前。
什么是头文件重复包含？
当同一个头文件被多个 #include 指令（直接或间接）拉入同一翻译单元时，就发生了重复包含。编译器会把内容原样展开，若头文件里有类定义、函数声明、宏定义等，重复展开会导致 redefinition 错误，比如：
error: redefinition of 'class MyWidget'
error: redefinition of macro 'LOG_LEVEL'
这不是链接期问题，是预处理阶段就挂了。
#pragma once 能用吗？
能，但有局限性。
#pragma once 是主流编译器（MSVC、Clang、GCC 5.0+）都支持的非标准但事实通用的防重机制。它让预处理器记录已见过的物理文件路径，再次遇到相同路径就跳过。
- ✅ 简洁：一行搞定，不用配守卫名
- ✅ 不怕宏名冲突：不依赖宏定义，不存在
MY_WIDGET_H和别人撞名的问题 - ❌ 跨硬链接/符号链接可能失效：同一文件通过不同路径被 include（如
./a.h和../proj/a.h），部分旧版编译器可能视为两个文件 - ❌ 极端场景下不被某些嵌入式工具链或静态分析器完全识别
适用场景：内部项目、团队统一工具链、快速原型；不建议用于需强可移植性的公共库。
传统 include 守卫怎么写才不出错？
标准、可移植、100% 可靠的方式是手动加宏守卫，三行固定结构：
#ifndef MY_HEADER_H #define MY_HEADER_H <p>// 头文件真实内容</p><div class="aritcle_card flexRow artxards"> <div class="artcardd flexRow"> <a class="aritcle_card_img" rel="nofollow" href="/xiazai/skill5502" title="C++ Code Review Master"><img src="https://img.php.cn/upload/skill/000/000/081/179051228971575.jpg" alt="C++ Code Review Master" onerror="this.onerror='';this.src='/static/lhimages/moren/morentu.png'" ></a> <div class="aritcle_card_info flexColumn"> <a rel="nofollow" href="/xiazai/skill5502" title="C++ Code Review Master" class="overflowclass">C++ Code Review Master</a> <p class="overflowclass">组合式C++代码评审方案，融合静态分析、AI推理、多轮迭代评审和C++专项检查，适用于PR审查、增量代码审查、全项目评审和代码质量评分，触发词包括review cpp、cpp代码评审、C++review、代码审查。</p> </div> <a rel="nofollow" href="/xiazai/skill5502" title="C++ Code Review Master" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span> </a> </div> </div><h1>endif // MY_HEADER_H</h1>
关键点：
-
MY_HEADER_H必须全局唯一：推荐用大写 + 下划线 + 文件名（如STRING_UTILS_H），避免只用UTILS_H这种泛化名 - 守卫宏名不能和项目中其他宏、类型、变量重名，否则可能静默失效（比如你定义了
int STRING_UTILS_H = 42;，后续#ifndef就永远为假） - 守卫必须严格包裹全部内容，包括
#include其他头文件的语句——漏掉任何一行都可能导致重复展开 - 不要写成
#if !defined(MY_HEADER_H)：虽然语义等价，但可读性差，也容易手误少个括号
能不能两个一起用？
可以，而且不少团队这么干：既写 #pragma once，又加传统守卫。
#pragma once #ifndef MY_HEADER_H #define MY_HEADER_H <p>// ...</p><h1>endif</h1>
这不是“更保险”，而是分层兜底：
- 主流编译器走
#pragma once路径，速度快（不用宏展开判断） - 遇到不支持
#pragma once的冷门编译器（如某些老版本 ICC 或定制交叉工具链），退回到守卫逻辑
但注意：顺序不能反——#pragma once 必须放在守卫之前，否则预处理器可能还没走到它就因守卫跳过了整段。
头文件防重看着简单，实际最容易栽在命名随意、跨平台构建遗漏、或守卫被意外注释掉这种地方。只要宏名够唯一、结构没剪裁、路径没歧义，基本不会出问题。
C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
