头文件更稳妥的做法，是单独放进与src/平级的include/目录；引用本地头文件时，使用#include "xxx.h"，并在编译阶段补上-Iinclude参数；为避免重复包含，通常优先采用#pragma once；同时，头文件之间的依赖关系要尽量收紧，别把内部细节一层层暴露出去，更要避开循环依赖这类问题。

头文件该放哪？

别塞进 src/ 里

头文件不是源码，它只负责声明，不参与编译成 .o；但所有用到它的 .cpp 文件都得能找得到它。

硬塞进 src/ 会导致路径混乱、#include 写法不统一，还容易被误删或重复编译。

标准做法是单独建 include/ 目录，和 src/ 并列：

• include/function.h —— 所有对外暴露的接口放这里
• src/function.cpp —— 实现写在这里，#include "function.h"
• src/main.cpp —— 同样用 #include "function.h"，不写相对路径如 ../include/function.h

编译时用 -Iinclude 告诉 Clang 去哪找头文件，而不是靠 #include "../include/..." 这种脆弱写法。

怎么写 #include 才不会出错？

引号 vs 尖括号

用双引号 "xxx.h" 表示本地头文件（项目自己的），用尖括号 表示系统或第三方库（如 ）。

Clang 按顺序搜索：-I 路径 → 系统路径。混用会失败。

• #include "car_control.h" 正确，Clang 先查 -Iinclude 下的 car_control.h
• #include 错误，Clang 会跳过 -I 直接去系统目录找，大概率报 fatal error: 'car_control.h' file not found
• #include "include/car_control.h" 不推荐，把路径细节暴露在代码里，迁移或重构时全得改

防止重复包含

#pragma once 还是 include guard？

两个都行，但 #pragma once 更轻量、不易出错，现代 Clang 完全支持。

include guard 容易手误写错宏名，比如：

#ifndef FUNCTION_H
#define FUNCTION_H
// ... 内容
#endif

如果复制粘贴后忘了改 FUNCTION_H，就白写了。

而 #pragma once 一行搞定：

#pragma once
void printHello();

注意：#pragma once 在极少数老旧构建系统或跨平台 CI 中可能不被识别（罕见），此时才退回到 include guard。

多级头文件依赖怎么管？

别让 main.cpp 直接 include 深层头文件

假设 utils.cpp 用了 math_utils.h，而 main.cpp 只调用 utils.cpp 提供的函数，那么 main.cpp 就不该 #include "math_utils.h"。

否则会带来这些问题：

• 修改 math_utils.h 会导致 main.o 重新编译，哪怕 main.cpp 根本没动
• 暴露了不必要的实现细节，破坏封装
• 增加循环依赖风险（比如 A.h 包含 B.h，B.h 又反过来包含 A.h）

更稳妥的做法是：只在确实有必要声明的地方再写进去。

头文件之间同样要尽量保持最小依赖。如果 utils.h 只是用到了 math_utils.h 中的一个类型，那就优先用前置声明 struct MathResult; 来代替 #include；只有在必须拿到完整定义的时候，才需要真正包含对应头文件。

最后提醒

头文件路径和包含方式看着琐碎，但一旦定型就很难改。

尤其在多人协作或接入 CI 时，-I 路径写错、#include 类型用混、或者依赖链太深，都会导致编译失败且错误信息模糊。

宁可花五分钟理清结构，别等改了十处 #include 才发现漏了一个 -I。

《夸克》非常好用的免费AI浏览器

下载APP查看