fatal error: xxx.h 头文件找不到速查
更新时间：2026-10-24。FAQ 速查页，面向在 Linux/macOS 上用 gcc/g++ 编译 C/C++ 工程的同学。fatal error: xxx.h: No such file or directory 是编译阶段的招牌报错：预处理器顺着
#include找头文件，搜完所有该找的目录也没找到，当场停机。报错的指向极其明确——引号或尖括号里那个文件名就是全部线索，问题只出在「它实际在哪」与「编译器被允许去哪找」之间的落差：-I路径漏加、相对路径的基准想错了、文件名大小写不一致、该头文件是构建期生成的而生成步骤没先跑、第三方库的开发包压根没装、或路径里带空格被拆成了两半。本篇以报错原文为锚逐条定位；如果头文件都找到了、链接阶段才炸符号，请转 undefined reference 链接错误速查。
本文要回答的问题
#include "util.h"和#include <util.h>的搜索路径差别在哪？- 头文件明明就在工程里，编译器为什么说找不到？
- 在 Mac 上好好的，到 Linux CI 上就报这个错，怎么回事？
- protobuf/yacc 生成的
.h报找不到，和普通头文件有什么不同？ - 怎么用一条命令看编译器到底搜了哪些目录？
一、报错原文与典型现象
报错固定长这样（工程路径以 /proj/demo 占位）：
$ make
cc -c -o build/main.o src/main.c
/proj/demo/src/main.c:3:10: fatal error: util.h: No such file or directory
3 | #include "util.h"
| ^~~~~~~~
compilation terminated.
make: *** [Makefile:12: build/main.o] Error 1第三方库版本：
/proj/demo/src/net.c:5:10: fatal error: curl/curl.h: No such file or directory
5 | #include <curl/curl.h>
| ^~~~~~~~~~~~~读懂报错抓住三件东西：找不到的文件名（缺谁）、引用它的源文件与行号（谁要它）、该次编译命令行上的 -I 列表（编译器被允许去哪找）。compilation terminated. 只是收尾声明，没有额外信息；真正的信息全在 fatal error 那一行和上面的编译命令里。
二、病因处置速查表
| 报错现象 / 场景 | 可能原因 | 快速验证 | 处置 |
|---|---|---|---|
| 找不到的头文件就在工程某子目录 | -I 没加该目录 | 看编译命令行有没有对应 -I | makefile/CMake 补 -Isrc/util 或 include_directories |
#include "../include/x.h" 找不到 | 相对路径基准理解错：引号 include 先相对当前源文件 | ls 以源文件位置为基准核对该相对路径 | 改相对层级，或改用 -I 加尖括号 include |
文件名 Util.h vs util.h | 大小写不匹配，大小写敏感文件系统才炸 | ls 打真实文件名逐字母比对 | 统一文件名大小写（建议全小写） |
找不到的是 xxx.pb.h、y.tab.h | 生成文件，生成规则没先执行 | ls 生成物是否存在，make -n 看依赖顺序 | 给生成的头文件写显式依赖，先跑生成步骤 |
找不到 <curl/curl.h> 这类系统头 | 库的运行时装了、开发包没装 | ls /usr/include/curl/ 或 pkg-config --cflags libcurl | 装开发包（-dev/-devel），用 pkg-config 取路径 |
头文件在但编译报一半 -I 路径被拆开 | 路径含空格，makefile 里没加引号 | 看编译命令行 -I 是否被空格截断 | 路径避免空格，或 makefile 里整体加引号 |
| 多层 include 后深层头找不到 | 嵌套 include 的搜索基准不是顶层源文件 | 沿 include 链逐层确认相对路径 | 统一用 -I 加工程根，include 写根相对路径 |
| 交叉编译时报系统头找不到 | sysroot 不对，找到的是宿主头路径 | 看编译命令 --sysroot= 参数 | 修正 sysroot，用工具链自带的 sysroot |
三、排查决策图
下面这张图是按「头文件实际存不存在」分岔的标准路线，颜色按角色区分：红是报错入口与命中的根因，蓝是排查动作，绿是通过分支，橙是修复动作，紫是防复发沉淀。
读这张图抓住一个分水岭：先在磁盘上找这个头文件的实体。找不到（左支）是事实层——生成步骤没跑、开发包没装、名字大小写对不上；找得到（右支）是搜索层——-I 没覆盖、相对路径基准错了、路径被空格拆碎。两支修法不重叠，先分清楚再动手。
四、逐条排查展开
第一步：先在磁盘上把文件实体找出来。 一招定左右支：
find /proj/demo -name 'util.h'
# /proj/demo/src/util/util.h （文件在，但不在搜索路径里 → 右支）
# 无任何输出 （文件真不在 → 左支）文件存在时：让编译器自己招供它搜了哪些目录。 gcc 预处理器有现成的调试开关：
echo '#include "util.h"' | cc -E -v - 2>&1 | sed -n '/search starts/,/End of search/p'这段输出会完整列出引号 include 与尖括号 include 各自的搜索目录清单，把 find 到的真实路径往清单里一对，缺哪个目录就补哪个 -I。引号与尖括号的差别记住一句话：#include "x.h" 先从当前源文件所在目录找，找不到再走 -I 与系统路径；#include <x.h> 跳过当前目录，直接走 -I 与系统路径。所以 ../include/x.h 这类相对写法相对的是源文件的位置而不是工程根——源文件挪一层目录，相对路径就全断。
makefile 与 CMake 各自的正确加法。 makefile 里补 CFLAGS += -I/proj/demo/src/util；CMake 里用 target_include_directories(app PRIVATE src/util)（优先于全局 include_directories，作用域干净）。补完 make -n 空跑一眼，确认 -I 真出现在了编译命令行上。
文件不存在时的三种典型。 一是生成文件没先生成：protobuf 的 .pb.h、bison/yacc 的 .y.h、autoconf 的 config.h 都是构建产物，makefile 必须给依赖它的 .o 写明对生成头的显式依赖（build/main.o: build/gen/util.pb.h），否则并行构建（make -j）时编译抢在生成前面必炸。二是第三方库只装了运行时：能跑不代表能编，编译要的头文件在开发包里——Debian/Ubuntu 装 libcurl4-openssl-dev、Fedora 装 curl-devel，装完用 pkg-config --cflags libcurl 直接取该加的 -I。三是大小写：macOS 默认大小写不敏感，#include "Util.h" 引 util.h 本地能过，Linux CI 立刻 fatal error，修法是全库统一小写文件名。
路径含空格是 make 的天敌。 make 按空白分词，-I/proj/my demo/include 会被拆成 -I/proj/my 和 demo/include 两个参数，前一个目录不存在、后一个不是选项，报错五花八门。工程路径全程避免空格是正解；绕不开就在 makefile 里整体加引号 "$<" 这类自动变量配合引用，并实测 make -n 的输出。
五、规范做法与预防
- include 一律工程根相对：
-I指到工程根（或统一的 include 目录），源文件里写#include "util/util.h"，不依赖../层级，挪文件不断链。 - 生成物显式依赖：凡是构建期生成的头文件，依赖它的目标必须显式依赖生成规则，并行构建才安全。
- CI 跑干净环境：开发机装过的 dev 包 CI 上没有，「包没装」这类问题 CI 一抓一个准；macOS 开发的项目加 Linux CI，大小写问题同理。
- 用 pkg-config 不手写路径：第三方库的
-I/-L让pkg-config --cflags --libs生成，换发行版不漂移。 - 文件名全小写：跨平台项目的头文件命名强制小写，从根上消掉大小写敏感事故。
这一篇在知识体系里的位置
本篇是 Makefile 排错速查簇的编译预处理篇，定位「编译第一步预处理器就找不到头文件」：头文件路径问题看本篇；make 展开规则就失败的看 make: No rule to make target 报错速查；编译被权限卡住的看 构建 Permission denied 报错速查；编译过了链接炸符号的看 undefined reference 链接错误速查；CMake 配置阶段问题的看 CMake 版本不兼容报错速查 与 CMake 找不到编译器速查。find、cc -E -v、pkg-config 三件排查套在所有头文件类报错间完全通用。
一句话总结
fatal error: xxx.h 先 find 确认头文件实体在不在：不在，是生成步骤没先跑（补显式依赖）、开发包没装（装 -dev/-devel 用 pkg-config 取路径）或大小写不匹配（统一小写）；在，用 cc -E -v 列出真实搜索目录清单，缺哪个目录补哪个 -I，相对 include 改掉 ../ 依赖、统一工程根相对写法。路径别带空格、生成物显式依赖、CI 干净环境兜底，这条报错即可基本绝迹。