最常见原因是头文件未加include guard或#pragma once，导致同一头文件被多次包含而引发类重复定义；可靠解法是二者选一：用#ifndef/#define/#endif守卫或#pragma once指令。
头文件没加 include guard 或 #pragma once
这是最常见原因：同一个头文件被多个源文件（或同一源文件中多次）包含，导致类定义重复出现。C++ 编译器在预处理阶段把 #include 直接展开，如果没防护，class xxx 就会被读两遍以上。
解决方式只有两个可靠选择，二选一即可：
- 用传统 include guard：
#ifndef MY_HEADER_H<br>#define MY_HEADER_H<br><br>class xxx { /* ... */ };<br><br>#endif注意MY_HEADER_H要全局唯一，推荐用文件名大写 + _H 后缀，比如QUEUE_IMPL_H - 用
#pragma once（现代编译器都支持，包括 MSVC、Clang、GCC 5.0+）：#pragma once<br><br>class xxx { /* ... */ };更简洁，但极少数老旧构建环境或特殊路径下可能失效（比如硬链接或符号链接混用）
在 .cpp 文件里写了类定义而不是只写声明
有人习惯把 class xxx 定义直接写在 .cpp 里，结果又在别处 #include "xxx.cpp" —— 这不是常规做法，但真有人这么干，尤其初学者模仿“头文件里只放声明”的思路时搞反了。
后果是：每个包含它的编译单元都会生成一份 class xxx 定义，链接前就报 redefinition。
立即学习“C++免费学习笔记（深入）”；
组合式C++代码评审方案，融合静态分析、AI推理、多轮迭代评审和C++专项检查，适用于PR审查、增量代码审查、全项目评审和代码质量评分，触发词包括review cpp、cpp代码评审、C++review、代码审查。
- 类定义（含成员函数体）必须只出现在一个地方：要么在头文件（配合 include guard），要么在某个
.cpp里且**不被任何头文件包含** - 如果类定义在
xxx.cpp中，其他文件要用它，只能在对应头文件xxx.h中写前向声明（如class xxx;）或完整声明（不含函数体），然后#include "xxx.h" - 切忌在头文件里写
#include "xxx.cpp"—— 这属于构建逻辑错乱
模板类定义放头文件但没处理显式实例化冲突
模板类（如 template<typename T> class xxx）的定义通常必须放在头文件，否则链接时报 undefined reference。但这会带来新风险：如果多个 .cpp 都实例化了同一个特化（如 xxx<int>），而你又在头文件里实现了成员函数体，就可能触发 ODR（One Definition Rule）违规，某些严格模式下报 redefinition。
- 确保所有模板成员函数定义都在头文件内联（即写在类体内，或加
inline关键字） - 避免在头文件里做显式实例化（如
template class xxx<int>;），除非你明确控制只在一个.cpp里写一次 - 如果非要分离实现，用
xxx.tpp并在头文件末尾#include "xxx.tpp"，而非让多个源文件各自去包含它
命名空间嵌套或 using 导致意外重定义
看起来不像重复，但实际是：你在不同头文件里写了 namespace A { class xxx { ... }; } 和 namespace A { class xxx { ... }; }，而这两个头文件又被共同包含——这时编译器认为是同一作用域下的两次定义。
更隐蔽的是 using namespace A; 后又定义同名类，或者嵌套过深（namespace A { namespace B { class xxx; } } 和 namespace A::B { class xxx; } 混用）。
- 检查所有涉及该类的命名空间拼写是否完全一致（包括空格、换行、缩进不影响，但大小写和嵌套层级必须相同）
- 避免在头文件顶部写
using namespace xxx;，尤其不要在系统/第三方命名空间上这么干 - 用完整作用域限定检查定义点：
namespace A::B { class xxx { ... }; }是 C++17 起才安全的写法；老标准建议统一用大括号嵌套
真正麻烦的不是语法层面怎么写，而是项目变大后，头文件依赖链变得不可见——某个中间头文件悄悄包含了你已引入的定义，而 IDE 不高亮、编译器只报最后一行。这时候得靠 g++ -E 看预处理结果，或启用 -H 查看头文件包含树。
