头文件重复包含本身不报错，但引发符号/类型重定义或模板多次实例化；#pragma once依赖路径判断且非标准，#ifndef依赖宏名且为标准方案；实际应分层使用：内部头文件首选#pragma once，公共头文件必用#ifndef守卫。
为什么头文件重复包含会导致编译错误
重复包含本身不直接报错，但会引发符号重定义、类型重定义或模板多次实例化等问题。比如在 utils.h 中定义了 struct Config { int port; };，若被两个源文件通过不同路径间接包含两次，g++ 会报 error: redefinition of 'struct Config'。
根本原因是预处理器不做语义判断，只机械展开文本——它不知道你“本意”是只定义一次。
#pragma once 和 #ifndef 的本质区别
#pragma once 是编译器扩展指令，由编译器识别并保证同一物理文件只被包含一次；#ifndef 是标准预处理机制，靠宏名唯一性做守卫，依赖程序员手动命名（如 UTILS_H_）。
关键差异：
-
#pragma once判断依据是文件路径（inode 或绝对路径），软链接、硬链接、符号路径不同可能导致误判 -
#ifndef完全基于宏名字符串，与路径无关，但宏名冲突（比如两个库都用COMMON_H）就失效 -
#pragma once解析更快，尤其大型项目中跳过文件 I/O；#ifndef每次仍需打开头文件读取守卫宏 - 所有主流编译器（Clang、GCC ≥5.0、MSVC）都支持
#pragma once，但它不是 C++ 标准，ISO C++ 标准只规定#ifndef
实际项目中怎么选：别二选一，要分层用
推荐组合策略：
- 自己写的内部头文件：首选
#pragma once，简洁不易出错，配合 IDE 自动补全很顺手 - 需要跨平台兼容老旧工具链（比如某些嵌入式编译器）或发布给第三方的公共头文件：必须用
#ifndef守卫，宏名建议含项目名和路径（如MYLIB_CORE_STRING_H_） - 混合使用没问题——
#pragma once在前，#ifndef守卫在后，编译器优先走#pragma once，不支持时自动 fallback（GCC/Clang 都能正确处理这种写法）
示例 mylib/string.h：
立即学习“C++免费学习笔记（深入）”；
#pragma once #ifndef MYLIB_STRING_H_ #define MYLIB_STRING_H_ #includenamespace mylib { std::string trim(const std::string& s); } #endif // MYLIB_STRING_H_
容易被忽略的坑：头文件里定义变量或函数
即使加了 #pragma once 或 #ifndef，如果在头文件里写了：
-
int global_counter = 0;→ 多个 TU 包含后导致 ODR 违反，链接时报multiple definition -
void helper() { ... }（非 inline / static）→ 同样触发多重定义 - 模板以外的内联函数没加
inline关键字 → C++17 前可能被多个 TU 实例化，违反 ODR
真正防重定义，靠的是定义位置 + 链接属性，不是包含守卫。头文件里只放声明、inline 函数、模板、constexpr 变量；实现在 .cpp 里。
守卫解决的是“文本重复展开”，不是“符号重复定义”。这点混淆是很多 C++ 新手调试数小时才意识到的。
