头文件中只能放声明，函数实现、全局变量初始化等定义必须放在.cpp文件中，否则被多文件包含会导致链接时multiple definition错误。
头文件里只能放声明，不能放定义
很多人一拆分就报 multiple definition 错误，根本原因是把函数实现、全局变量初始化写进了 .h 文件。头文件被多个 .cpp 包含后，每个编译单元都生成一份定义，链接时直接冲突。
实操建议：
立即学习“C++免费学习笔记（深入）”；
- 函数体、
Static以外的全局变量初始化、模板以外的类成员函数实现，一律挪到.cpp文件里 - 头文件中用
inline标记短小函数（如 getter），或用constexpr替代简单计算 - 类定义可以完整放在头文件，但成员函数若逻辑稍长，优先在
.cpp中实现 - 用
#pragma once或传统#ifndef XXX_H守卫，避免重复包含——但这不解决定义重复问题
源文件怎么写才能被正确链接
.cpp 文件不是独立运行的，它只负责生成目标文件（.o 或 .obj），最终靠链接器拼起来。如果某个 .cpp 没参与编译，或者函数名拼错、签名不一致，就会报 undefined reference。
实操建议：
立即学习“C++免费学习笔记（深入）”；
- 确保每个
.cpp都显式包含它所实现的头文件（比如utils.cpp开头写#include "utils.h"），编译器能借此校验声明与定义是否匹配 - 函数名、参数类型、const 修饰、返回值必须完全一致；
int foo()和int foo(void)在 c++ 中等价，但和int foo(int)就是两个函数 - 不要在
.cpp里重复写extern "C"——除非你真在混用 C 符号；C++ 成员函数名会被 mangling，别手动干预 - 构建时所有
.cpp必须一起传给编译器，例如：g++ main.cpp utils.cpp -o app；用 Makefile 或 CMake 时，确保它们都在源文件列表里
模板类为什么不能拆成 .h + .cpp
模板不是普通函数，它没有具体类型，编译器得看到完整定义才能实例化。如果把模板实现写在 .cpp 里，其他 .cpp 包含头文件时，只有声明、没有定义，链接必然失败。
实操建议：
立即学习“C++免费学习笔记（深入）”；
- 模板声明和定义都放在头文件里（常见做法）；
.cpp文件只留空或删掉 - 想分离实现可加
inline或用显式实例化：在某个.cpp里写template class MyStack<int>;</int>，但仅限你明确知道要用哪些类型 - 别信“把模板实现放到
.tpp再#include”这种折中方案——它只是把代码藏起来了，本质还是头文件内定义 - 编译错误信息里出现大量
no matching function for call to ...，且涉及模板参数推导失败，大概率是定义不可见
include 路径和 #include “” vs 的区别
写错路径或引号类型，轻则找不到头文件，重则意外包含了系统同名头文件（比如你写了 #include <String.h></string.h>，却想用自己写的 string.h），行为完全失控。
实操建议：
立即学习“C++免费学习笔记（深入）”；
- 项目内头文件一律用双引号：
#include "utils.h"；系统/第三方头文件用尖括号：#include <vector></vector> - 编译时用
-I指定头文件根路径，比如头文件在include/utils.h，就加-Iinclude，然后代码里写#include "utils.h"，而不是#include "include/utils.h" - 避免相对路径嵌套太深：
#include "../../src/core/data.h"—— 这种写法脆弱，重构目录就崩 - CMake 中用
target_include_directories(app private include)替代裸-I，更可靠
最常被忽略的是：头文件守卫只防重复包含，不防重复定义；而模板定义必须可见——这两点交叉出的问题，调试起来特别像“随机失败”。拆分不是为了整齐，是为了让每个编译单元职责清晰、依赖明确。一旦开始怀疑链接问题，先看 nm 输出目标文件里的符号，比猜快得多。