头文件重复包含指同一头文件被多次#include而未防护，导致类/函数重复定义等错误；可用#pragma once（快但非标）或宏卫士（标准但稍慢），推荐两者并用兼顾效率与兼容性。
什么是头文件重复包含，为什么它会出问题
当多个源文件（或同一源文件中多次）通过 #include 引入同一个头文件，而该头文件又没做防护时，编译器就会把它的内容原样展开多次。这会导致：类/函数重复定义、宏重复定义、模板实例化冲突等错误，典型报错如 error: redefinition of 'class XXX' 或 error: 'YYY' declared as an inline function。
根本原因不是 #include 本身有问题，而是 C++ 编译模型基于“翻译单元”——每个 .cpp 文件独立预处理+编译，头文件只是文本复制粘贴进去。
用 #pragma once 最快但不完全跨平台
#pragma once 是绝大多数现代编译器（GCC、Clang、MSVC）都支持的非标准但事实通用的防重包含指令，加在头文件最开头即可：
#pragma once
<h1>include <vector></vector>
</h1><p>class Widget { /<em> ... </em>/ };</p>
优点是简洁、无命名冲突风险、编译器可直接跳过文件读取，略快于宏卫士。
缺点是 C++ 标准未规定其行为，极少数嵌入式或老编译器（如某些 TI C++ 编译器）可能不识别；另外，若同一文件被不同路径（如软链接、符号链接、挂载路径差异）引入，部分旧版编译器可能误判为不同文件而失效。
用传统宏卫士（include guard）最稳妥
这是 ISO C++ 标准保证支持的方式，靠预处理器宏控制展开逻辑：
#ifndef MY_HEADER_H #define MY_HEADER_H <h1>include <string></string> </h1><p>void log_message(const std::string& s);</p><div class="aritcle_card flexRow artxards"> <div class="artcardd flexRow"> <a class="aritcle_card_img" rel="nofollow" href="/xiazai/gongju/2823" title="C++14"><img src="https://img.php.cn/upload/manual/001/431/639/6ac8b33c327c4749.png" alt="C++14" onerror="this.onerror='';this.src='/static/lhimages/moren/morentu.png'" ></a> <div class="aritcle_card_info flexColumn"> <a rel="nofollow" href="/xiazai/gongju/2823" title="C++14" class="overflowclass">C++14</a> <p class="overflowclass">C++14 对 C++11 的修正与增强版本，适合旧系统维护和较老工具链兼容。</p> </div> <a rel="nofollow" href="/xiazai/gongju/2823" title="C++14" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span> </a> </div> </div><h1>endif // MY_HEADER_H</h1>
注意三点：
-
MY_HEADER_H必须全局唯一，建议用项目名+路径+文件名大写+下划线组合，比如NETWORK_HTTP_CLIENT_H - 不要只用简单名如
UTILS_H，容易和其他库冲突 - 宏名末尾加
_H是常见惯例，但不是强制；关键是避免和用户代码、标准库宏重名
现代项目推荐两者并用，兼顾安全与效率
虽然单独用任一种都够用，但大型项目或开源库常采用“双保险”写法：
#pragma once #ifndef MY_HEADER_H #define MY_HEADER_H <p>// 头文件主体内容</p><h1>endif // MY_HEADER_H</h1>
这样既享受 #pragma once 的速度优势，又保留宏卫士作为兜底——万一遇到不支持 #pragma once 的环境，仍能正确工作。GCC 和 Clang 在看到 #pragma once 后，即使宏卫士也存在，通常也不会多做一次文件读取，所以没有实际性能损失。
真正容易被忽略的是：宏卫士名称必须与头文件物理路径强相关，且不能依赖构建系统生成的变量。有人试图用 FILE 或 CMake 自动生成宏名，反而破坏可移植性——预处理器不认识这些，会导致卫士失效。
C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
