目录

开发笔记：VSCode + Qt + clangd 明明能正常运行却满屏红波浪线

前言

一、问题现象

二、根本原因：两套工具互不沟通

三、完整解决方案

方案 1：配置 .clangd（最推荐、最根治）

方案 2：自动生成 compile_commands.json

方案 3：代码层面简单清理

方案 4：懒人兜底（不想配置就关掉）

四、总结

---

前言

最近在用 VSCode 搭配 MinGW 开发 Qt 项目，遇到一个特别典型的问题：代码编译、运行完全正常，功能一点问题都没有，但编辑器里全是红色报错波浪线，提示找不到头文件、未定义标识符、不识别编译参数等。

折腾一番后彻底搞懂了原因，这里做一篇完整记录，方便以后复用。

---

一、问题现象

项目可以正常 qmake + mingw32-make，生成的 exe 也能跑起来，但 VSCode 里持续报以下几类错误：

mainwindow.h file not found
ui_mainwindow.h file not found
type_traits file not found

1. Qt 类型不识别

   Unknown type name 'QWidget'
   Unknown type name 'QString'
   Use of undeclared identifier 'MainWindow'
   

2. 编译选项不兼容

   Unknown argument: '-fno-keep-inline-dllexport'
   Unsupported option '-mthreads'
   

简单说：编译器认，编辑器不认。

---

二、根本原因：两套工具互不沟通

核心就一句话：真正编译项目的 MinGW，和 VSCode 做代码提示的 clangd，是两套完全独立的工具。

• 项目构建：使用 MinGW/g++
  • 目标平台：x86_64-w64-windows-gnu
  • 自带 Qt 头文件路径、宏定义、依赖配置
• 静态分析：使用 clangd
  • 默认目标平台：x86_64-pc-windows-msvc（VS 编译器）
  • 不知道 Qt 装在哪
  • 不认识 MinGW 专属编译参数
  • 没定义 Qt 必需的宏（QT_CORE_LIB 等）

所以出现了最离谱的情况：程序跑得飞起，clangd 却一脸懵圈。

---

三、完整解决方案

方案 1：配置 .clangd（最推荐、最根治）

在 Qt 项目根目录新建文件 .clangd，内容如下（路径按自己环境改）：

CompileFlags:
  Add:
    # 强制 clangd 使用 MinGW 目标
    - "--target=x86_64-w64-windows-gnu"
    
    # 项目头文件路径
    - "-Iinclude"
    - "-Isrc"
    
    # Qt 安装路径（改成你自己的）
    - "-ID:/software/QT/6.10.2/mingw_64/include"
    - "-ID:/software/QT/6.10.2/mingw_64/include/QtCore"
    - "-ID:/software/QT/6.10.2/mingw_64/include/QtGui"
    - "-ID:/software/QT/6.10.2/mingw_64/include/QtWidgets"
    
    # MOC / UI 自动生成文件路径
    - "-Ibuild/moc"
    - "-Ibuild/ui"
    
    # C++ 标准与宏
    - "-std=c++17"
    - "-DUNICODE"
    - "-D_UNICODE"
    - "DQT_CORE_LIB"
    - "DQT_GUI_LIB"
    - "DQT_WIDGETS_LIB"

  # 移除 clangd 不认识的 MinGW 参数
  Remove:
    - "-fno-keep-inline-dllexport"
    - "-mthreads"

保存后，杀掉 clangd.exe 重启 VSCode，大部分红波浪线直接消失。

---

方案 2：自动生成 compile_commands.json

在你的 .pro 文件中加一行：

CONFIG += compile_commands_json

执行：

qmake

构建目录会生成 compile_commands.json，把它复制到项目根目录。clangd 会自动读取所有编译参数，一劳永逸。

---

方案 3：代码层面简单清理

很多报错是多余头文件导致的，顺手清理一下：

• 纯手写 UI、没有用 .ui 文件 → 删除 #include "ui_mainwindow.h"
• 使用 QMenu、QAction 等 → 补上对应头文件，如 #include <QMenu>
• 路径避免中文、空格，clangd 对中文路径支持很差

---

方案 4：懒人兜底（不想配置就关掉）

如果只是不想看红波浪线，直接关闭错误提示：

VSCode 设置搜索：

C_Cpp.errorSquiggles

设为 Disabled 即可。（不推荐，会掩盖真实错误）

---

四、总结

1. VSCode 报红 ≠ 代码错误，多半是 clangd 没配置对环境
2. 核心矛盾：MinGW 编译 vs clangd 默认 MSVC 目标
3. 最优解：.clangd 指定目标平台 + 头文件路径 + Qt 宏
4. 一劳永逸：用 compile_commands.json 让 clangd 跟编译器保持一致
5. 代码层面：清理无用头文件，避免中文路径

这套配置之后，VSCode + Qt + MinGW 开发体验基本接近 Qt Creator，又能保留 VSCode 的轻便与插件生态。