重复包含头文件会导致重定义错误，因类声明、宏等被多次展开；#pragma once由编译器按路径判重，高效但非标准；卫哨宏兼容性好但需规范命名；二者可共存，但须统一团队规范。

为什么重复包含头文件会出问题

当多个源文件或同一文件多次 #include 同一个头文件时，若头文件里定义了类、函数声明、宏或内联函数，编译器可能报 redefinition 错误。比如在 utils.h 中写了

class Logger { /* ... */ };

，又被 A.cpp 和 B.cpp 同时包含，且两者都编译进同一程序，链接阶段虽可能不报错，但宏、模板特化、静态变量定义等会直接触发编译失败。

#pragma once 是什么，它怎么工作的

#pragma once 是编译器指令，告诉预处理器：如果当前头文件已被包含过，跳过后续内容。它不依赖宏名，而是由编译器根据文件的物理路径（或 inode）做唯一性判断。

• 速度快：不用展开宏、不增加预处理符号表负担
• 写法简单：

  #pragma once

  放在头文件最开头即可
• 主流编译器（MSVC、Clang、GCC 14+）都支持，但 GCC 在早期版本（如 4.8）中对符号链接或挂载点路径识别不稳定

但它不是 C++ 标准特性，属于编译器扩展——这意味着极端跨平台构建（比如用非常老的 ICC 或某些嵌入式工具链）时可能失效。

更兼容的方案：传统卫哨宏（include guard）

标准、可移植、100% 被所有 C++ 编译器支持。原理是用宏定义做标记：

#ifndef UTILS_H
#define UTILS_H
// 头文件实际内容
class Logger { / ... / };
endif // UTILS_H

注意要点：

• 宏名必须全局唯一，推荐用 大写文件名 + _H（如 STRING_UTILS_H），避免和项目其他宏冲突
• 不能只写 #ifndef XXX 而漏掉 #define XXX，否则无效
• 宏名中避免点号、连字符（.、-），它们不是合法宏名字符
• 放在头文件最顶部，且确保没有 BOM 或空行挡在 #ifndef 前面（否则可能被忽略）

两个方案能混用吗？有什么坑

可以，而且常见于大型项目（兼顾兼容性与现代编译器优化）：

#pragma once
#ifndef NETWORK_CLIENT_H
#define NETWORK_CLIENT_H
// 内容...
endif // NETWORK_CLIENT_H

但要注意：

• 某些旧版 Clang（如 3.4）在启用 -Wpragma-once-outside-header 时会对 #pragma once 在非 .h 文件中报警——确保它只出现在头文件里
• 如果头文件通过符号链接被不同路径包含（例如 /src/a.h 和 /build/a.h 指向同一文件），#pragma once 可能判为两个文件，而卫哨宏仍有效——这是它最易被忽略的兼容短板
• 不要依赖 #pragma once 来“替代”卫哨宏做逻辑控制（比如条件跳过某段代码），它只管整文件跳过

真正关键的不是选哪个，而是统一团队规范；一旦选了卫哨宏，就别在同一个项目里有的用 #pragma once、有的用宏——预处理器不会报错，但协作和审查成本会上升。