gcc中#include "xxx.h"先查当前源文件目录，再查-i路径和系统路径；#include 直接跳过当前目录，只查-i路径和系统路径。
头文件找不到？先确认 #include 路径写法是否匹配搜索顺序
GCC 对 #include "xxx.h" 和 #include <xxx.h></xxx.h> 的查找逻辑完全不同，这是绝大多数“找不到头文件”错误的根源。"xxx.h" 会优先在当前源文件所在目录找，再查 -I 指定路径；而 <xxx.h></xxx.h> 直接跳过当前目录，只按 -I 和系统默认路径顺序搜索。如果你把 utils.h 放在 ./inc/ 下，但代码里写的是 #include "utils.h"，而编译时没加 -I./inc，GCC 就不会去那个目录翻。
常见踩坑点：
- 误以为
#include "utils.h"会自动递归搜索子目录 —— 不会，它只查当前源文件目录和-I列表里的**一级路径** - 混用引号和尖括号：比如系统头文件用
"stdio.h"，或自定义头文件用<my_header.h></my_header.h>，都可能绕过预期路径 -
-I路径末尾带不带斜杠无所谓，但路径本身必须存在且可读（-I./inc和-Iinc效果不同，后者依赖当前工作目录）
多文件项目必须用 -c 分别编译，不能直接 gcc *.c -o app
直接把所有 .c 文件一股脑丢给 gcc 编译，看似省事，但一旦头文件路径不统一、宏定义冲突或函数重复定义，错误信息会非常模糊（比如报 multiple definition of 'func' 却不告诉你具体哪两个 .c 文件撞了）。正确做法是每个 .c 单独走一遍预处理+编译+汇编，生成各自的 .o，最后再链接。
实操步骤：
- 对每个
.c文件执行：gcc -c -I./inc main.c -o main.o（注意-I必须出现在每个gcc -c命令里） - 确保所有
.o文件都在同一目录下，再链接：gcc main.o utils.o -o app - 如果头文件里用了条件宏（如
#ifdef DEBUG），记得统一加-DDEBUG到每个gcc -c命令中，否则部分.o会看到宏，部分看不到
gcc -E 是调试头文件包含问题的唯一可靠手段
当你怀疑头文件没被正确包含、宏没展开、或者条件编译分支没生效时，不要靠猜，直接用 gcc -E 看预处理后的结果。它输出的是纯文本，里面每行开头的 # 行（如 # 1 "main.c"、# 2 "inc/utils.h" 2）清楚标出了当前代码来自哪个文件、哪一行，你能一眼看出 utils.h 是否真的被拉进来了、有没有被 #ifdef 删掉、宏替换是否符合预期。
实用技巧：
- 只看头文件包含链：
gcc -E main.c | grep '^#.*"[^"]*\.h"' | head -20，快速定位前几层 include 关系 - 检查某个宏是否定义：
gcc -E -dM main.c | grep DEBUG，比翻 Makefile 更直接 - 想确认
__GNUC__版本是否够用：gcc -E -dM -xc /dev/null | grep __GNUC__，避免依赖高版本特性却没报错
Makefile 不是必需品，但手写命令时 -I 和 -D 容易漏传
手动敲一长串 gcc -c -I./inc -I./src -DDEBUG -std=c11 foo.c -o foo.o 很容易少一个 -I 或者漏掉 -D，尤其当项目增加新头文件目录时。这不是语法问题，而是操作一致性问题 —— 某个 .c 编译时没带 -I./extra，它就看不到那个目录下的头文件，但错误可能直到链接阶段才暴露，排查成本陡增。
临时规避办法：
- 把所有头文件路径统一放到一个变量里，比如
INC="-I./inc -I./src"，然后每次调用都写gcc $INC -c ... - 用
gcc -v查看完整搜索路径，确认-I是否真被采纳（输出里会有search starts here:段） - 如果项目结构固定，直接把头文件全软链到当前目录：
ln -sf ../inc/*.h .，让#include "xxx.h"自然命中 —— 适合小项目快速验证，但别长期这么干
真正麻烦的不是命令怎么写，而是同一个宏在不同 .c 文件里被不同方式定义（有的靠 -D，有的靠头文件里 #define），导致行为不一致。这种问题 gcc -E 一眼能揪出来，但靠运行时现象去反推几乎不可能。
