编译期报错是“redefinition of 'xxx'”，链接期报错是“multiple definition of 'DoTask()'”；前者因同一.cpp内重复定义，后者因多个.o含同名符号，需分别通过头文件防护和声明/定义分离解决。
直接用 #pragma once 放在头文件第一行，95% 的项目问题当场消失。它不是“可选项”，而是现代 C++ 工程的默认起点。
报错是编译期还是链接期？先分清阶段再动手
重复包含本身不直接报错，真正触发错误的是它导致的 ODR（单一定义规则）违反。但错误表现分两类，处理思路完全不同：
- 编译期报
redefinition of 'xxx'：说明同一个.cpp文件里，某个符号（比如变量、函数、类）被定义了两次——大概率是头文件里写了int g_flag = 0;这类定义，且没加防护 - 链接期报
multiple definition of 'DoTask()'：多个.cpp各自编译通过，但链接时发现同名函数/变量在多个.o里都存在——说明头文件里放了非inline的函数实现或全局变量定义
前者改头文件防护 + 把定义挪到 .cpp；后者必须确保头文件只留声明，实现在源文件里写。
#pragma once 要怎么写才真正生效
它只有一条硬性要求：必须出现在头文件最开头，任何内容（包括注释、#include、空行）都不能在它前面。否则预处理器会忽略它。
立即学习“C++免费学习笔记（深入）”；
- ✅ 正确：
#pragma once #include <string> struct Config { std::string name; }; - ❌ 失效：
// config.h // 这个注释会让 #pragma once 失效 #pragma once #include <string>
（注释在前，#pragma once不再是首行） - ⚠️ 注意：
#pragma once对软链接、挂载路径不同但内容相同的文件可能失效，嵌入式项目或老工具链（如旧版 IAR）不识别，此时得 fallback 到#ifndef
为什么 #ifndef 守卫总失效？常见写错点
守卫宏不是摆设，写错就等于没写。最容易翻车的三个地方：
- 宏名大小写不一致：
#ifndef UTILS_H和#define utils_h不匹配 → 完全不生效 - 漏写
#define行：只剩#ifndef XXX_H和#endif→ 每次都跳过全部内容 - 宏名不够唯一：两个模块都用
COMMON_H，其中一个头文件被屏蔽后，另一个实际内容可能被意外展开
推荐命名法：PROJECT_MODULE_FILENAME_H，例如 MYAPP_NETWORK_HTTP_CLIENT_H，全大写 + 下划线 + _H 后缀，基本杜绝冲突。
头文件里写了 inline 函数或模板，还需要防护吗
需要。即使函数加了 inline、变量加了 constexpr、模板全在头文件里定义，重复包含仍可能引发 ODR 违反——尤其当不同编译单元看到的模板特化不一致，或 inline 函数内联展开后符号版本不统一时。
更关键的是：防护机制不是为“当前能编译”服务的，而是为“未来修改留余地”。今天你只声明，明天同事加了一行 int helper_counter = 0;，没防护的头文件立刻崩。
所以无论内容多“安全”，每个 .h 都该有防护。这不是过度设计，是防止协作中无声的雪崩。
