鸳鸯蝴蝶派1. 现象背后：clangd 的红波浪从哪里冒出来的
最近在 VSCode 里写一个 Qt 程序时，我又遇到了那个熟悉的画面：CMake 配置正常，程序编译、运行全都好端端的，窗口该弹出来就弹出来，按钮该响应就响应，但编辑器里从 main.cpp 到 MainWindow.cpp，再到各种自定义 QObject 子类，整屏都是红色波浪线，鼠标随便一放就是 "fatal error: 'QtWidgets/QApplication' file not found"。
这种事儿在 VSCode + Qt + clangd 的组合里太常见了。尤其是那种已经用命令行或者 Qt Creator 构建过一轮、又切回 VSCode 写代码的人，隔三差五就会碰上。第一次遇到时我也懵了：代码明明能跑，编译器也没意见，为什么 clangd 看起来像在骂街？
先别怀疑代码，也别急着删缓存重新装环境。红波浪线不是"编译错误"，它更像是 clangd 这个语言服务器在跟你说："我没拿到这个项目的编译上下文，所以我现在只能瞎猜。" 而 Qt 项目恰恰是 clangd 最容易猜错的那一类——因为 Qt 的头文件在安装时通常不会落到系统默认搜索路径里，而是被分散安排在 /usr/include/qt、/usr/include/x86_64-linux-gnu/qt6/QtWidgets、/usr/include/x86_64-linux-gnu/qt5/QtWidgets 或者 Qt 安装目录下的 include/QtWidgets 这些位置。真正的编译过程里，CMake 或 qmake 会把所有 include 路径通过 -I 参数传给 GCC 或 MSVC，编译器自然找得到。可 clangd 如果不加载 compile_commands.json，它就完全不知道这些临时参数，结果必然满屏红。
这篇笔记我不打算只给结论，我想把排查链路完整顺一遍。因为这次问题和我以前遇到过的还不太一样，程序能跑、clangd 也装了、compile_commands.json 也存在，红波浪还是在，最后折腾半天才发现是路径匹配和编译目录的问题。这类"看着正常却到处错"的情况，比单纯缺配置更折磨人。
1.1 先回放一次典型的"翻车现场"
我举一个我实际遇到过的错误面板截图式场景，你可以对照一下自己是不是也长这样：
main.cpp第一行#include <QApplication>报fatal error: 'QtWidgets/QApplication' file not found- 接着
QApplication app(argc, argv);报unknown type name 'QApplication' QMainWindow、QPushButton、QVBoxLayout这些类名全被标成未知标识符#include "ui_mainwindow.h"也报找不到文件- 然后问题面板像刷屏一样滚出几十条错误
如果错误是这样开头的，其实是个好消息：根因高度集中在"clangd 没拿到 Qt 头文件