VSCode 编译 Qt 5.12 QML 完整教程（Windows + MinGW）

qq_283720052026-03-28 12:50

本文以 Qt 5.12.x + MinGW + VSCode 为环境，从环境准备、项目创建、VSCode 配置到编译、运行、调试，提供完整可落地步骤，适配 QML 项目开发。

一、为什么需要使用VS　Code编译Qt

VS Code 并非编译 Qt/QML 的唯一 或官方首选 工具，但在当下开发环境中，它凭借轻量灵活 + 深度 AI 辅助的组合优势，成为越来越多开发者的"必需"选择。

1. 超越传统 IDE 的核心优势

优势维度 说明
轻量跨平台 启动快、资源占用低，Windows/macOS/Linux 体验一致，适合多环境开发。
强大扩展生态 官方 Qt 插件、CMake Tools、QML 语言服务器等，补齐了编辑器的 IDE 能力。
远程开发 Remote-SSH 让本地写代码、远程编译调试成为常态，尤其适合嵌入式、工控、服务器端 Qt 应用。
统一工作流 一个窗口同时处理 C++/QML/Python/JS，满足全栈或跨语言项目需求。

2. AI 辅助：VS Code 的"杀手锏"

VS Code 是 GitHub Copilot、通义灵码、Codeium 等前沿 AI 编程工具的 首发和优化主阵地，在 Qt/QML 开发中带来质的提升：

  • 智能补全与代码生成

    AI 能根据项目上下文（CMakeLists.txt 中的 Qt 版本、已定义模块）预测意图，自动生成信号槽连接、QML 绑定逻辑，甚至补全复杂的槽函数实现。

  • 上下文感知更强

    模型训练时大量使用了 GitHub 上的 Qt/QML 项目（大多配有 .vscode 配置），因此生成的代码更符合 Qt 最佳实践，能自动避免过时 API。

  • 代码理解与重构

    选中混合 C++/QML 代码，AI 能解释信号槽机制、setContextProperty 等交互逻辑；一键生成符合 QDoc 规范的注释，大幅降低文档维护成本。

  • 调试辅助

    AI 可分析编译/运行错误，给出针对性修复建议（如提醒添加 Q_OBJECT 宏），并在调试时解释复杂 Qt 数据结构（QString、QMap）的内部状态。

3. 与其他 IDE 对比：VS Code 的定位

工具 优势 局限 适合场景
Qt Creator 开箱即用，集成 Qt Designer、翻译工具，无需配置。 AI 生态弱，远程开发不便。 传统 Qt 开发，不需要 AI 重度辅助。
Visual Studio Windows 上调试强，MSVC 优化好。 臃肿，跨平台配置复杂，远程开发弱。 Windows 平台大型 C++ 项目。
VS Code 轻量、AI 生态最完善、远程开发一流。 需手动配置 CMake/Qt，缺少原生 UI 设计器。 追求 AI 辅助、远程/嵌入式开发、全栈项目。

4. 什么时候"需要" VS Code？

  • 你希望 AI 帮你编写大部分样板代码（信号槽、QML 绑定、CMake 配置），把精力集中在业务逻辑上。

  • 你需要在 远程设备（树莓派、工控机、服务器） 上开发 Qt 应用，并享受本地智能补全和调试。

  • 你的项目混合了 Python、JS 或其他语言，希望在统一界面下工作。

  • 你习惯 现代化的开发体验，愿意花十几分钟配置工具链，换来长期的高效产出。

VS Code 在 Qt/QML 开发中的价值，已从"可选的轻量编辑器"升级为 "AI 时代的高效开发平台" 。它不是 Qt 官方唯一推荐，但如果你希望 让 AI 成为你的结对编程伙伴，同时兼顾跨平台、远程开发等现代需求，VS Code 就是那个"需要"的选择。

二、环境准备（必做）

1. 安装 Qt 5.12（含 MinGW）

  • 下载：Qt 官网下载 Qt 5.12.x 离线安装包 （如 5.12.8），选择 MinGW 7.3.0 64-bit 组件（必须勾选 MinGW、Qt 5.12.x MinGW 64-bit、Qt Creator）。
  • 安装路径：建议 C:\Qt\Qt5.12.8（避免中文 / 空格路径）。
  • 验证：安装后，C:\Qt\Qt5.12.8\5.12.8\mingw73_64\bin 下有 qmake.exe；C:\Qt\Qt5.12.8\Tools\mingw730_64\bin 下有 mingw32-make.exe、g++.exegdb.exe;
  • vscode会用到上述命令.
  1. 配置系统环境变量（关键）

将以下路径添加到系统 PATH（重启电脑生效）：

复制代码 
C:\Qt\Qt5.12.8\5.12.8\mingw73_64\bin  

C:\Qt\Qt5.12.8\Tools\mingw730_64\bin

验证：打开 cmd，输入 qmake -v、g++ -v、mingw32-make -v，均输出版本信息即成功。

3. 安装 VSCode 及必备插件

  • 安装 VSCode（官网下载）。
  • 安装插件（扩展商店搜索）：
    1. C/C++（Microsoft）：C++ 语法、调试、智能提示。
    2. CMake Tools：如果打算使用 CMake 构建，此插件是必须的。
    3. Qt QML：提供 QML 语法高亮和智能提示。

三、创建 Qt 5.12 QML 项目（推荐用 Qt Creator 初始化）

VSCode 不支持直接创建 Qt QML 项目，先用 Qt Creator 生成标准项目，再用 VSCode 打开：

  1. 打开 Qt Creator → 新建项目 → 选择 Qt Quick Application - Empty → 项目名 QtQmlDemo → 路径 D:\Projects\QtQmlDemo → 构建工具选 qmake → 套件选 Desktop Qt 5.12.12 MinGW 64-bit → 完成。

2.项目结构（标准 QML 项目）：

plaintext

  1. 测试 Qt Creator 编译：点击「构建」→「运行」，能正常弹出 QML 窗口即项目有效。

四、VSCode 配置（核心步骤）

用 VSCode 打开项目文件夹 D:\Projects\QtQmlDemo，在项目根目录创建 .vscode 文件夹，配置 3 个核心文件。

1. 配置 c_cpp_properties.json（智能提示 / 头文件）

快捷键 Ctrl+Shift+P → 输入 C/C++: Edit Configurations (JSON)，生成并修改如下：

json

复制代码 
{
    "configurations": [
        {
            "name": "Win32",
            "includePath": [
                "${workspaceFolder}/**",
                "C:/Qt/Qt5.12.8/5.12.8/mingw73_64/include/**",
                "C:/Qt/Qt5.12.8/5.12.8/mingw73_64/include/QtQuick",
                "C:/Qt/Qt5.12.8/5.12.8/mingw73_64/include/QtQml"
            ],
            "defines": [
                "_DEBUG",
                "UNICODE",
                "_UNICODE"
            ],
            "compilerPath": "C:/Qt/Qt5.12.8/Tools/mingw730_64/bin/g++.exe",
            "cStandard": "c11",
            "cppStandard": "c++17",
            "intelliSenseMode": "windows-gcc-x64"
        }
    ],
    "version": 4
}

作用：让 VSCode 识别 Qt 头文件，解决 #include <QtQml> 报错、智能提示失效问题。

2. 配置 tasks.json（编译任务：qmake + make）

快捷键 Ctrl+Shift+P → 输入 Tasks: Configure Task → 选择 Create tasks.json file from template → Others，修改如下：

json

复制代码 
{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "build-qml",
            "type": "process",
            "command": "C:/Qt/Qt5.12.8/Tools/mingw730_64/bin/mingw32-make.exe",
            "args": [
                "-f",
                "Makefile"
            ],
            "options": {
                "cwd": "${workspaceFolder}/build",
                "env": {
                    "PATH": "C:/Qt/Qt5.12.8/Tools/mingw730_64/bin;C:/Qt/Qt5.12.8/5.12.8/mingw73_64/bin;${env:PATH}",
                    "QTDIR": "C:/Qt/Qt5.12.8/5.12.8/mingw73_64"
                }
            },
            "group": {
                "kind": "build",
                "isDefault": true
            }
        }
    ]
}

作用：定义「创建 build 目录 → qmake 生成构建文件 → make 编译」的自动化流程。

3. 配置 launch.json（调试配置：C++ + QML）

快捷键 Ctrl+Shift+P → 输入 Debug: Open launch.json → 选择 C++ (GDB/LLDB)，修改如下：

json

复制代码 
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Qt QML Debug",
            "type": "cppdbg",
            "request": "launch",
            "program": "${workspaceFolder}/build/debug/${workspaceFolderBasename}.exe",
            "args": [],
            "stopAtEntry": false,
            "cwd": "${workspaceFolder}",
            "environment": [
                {
                    "name": "PATH",
                    "value": "C:\\Qt\\Qt5.12.8\\Tools\\mingw730_64\\bin;C:\\Qt\\Qt5.12.8\\5.12.8\\mingw73_64\\bin;${env:PATH}"
                }
            ],
            "externalConsole": false,
            "MIMode": "gdb",
            "miDebuggerPath": "C:/Qt/Qt5.12.8/Tools/mingw730_64/bin/gdb.exe",
            "preLaunchTask": "build-qml"
        }
    ]
}

作用：配置 GDB 调试器，关联编译任务，支持 C++ 断点 + QML 调试。

五、编译、运行、调试（完整流程）

1. 编译项目（两种方式）

  • 方式 1：快捷键 Ctrl+Shift+B → 选择 make-debug，自动执行「mkdir → qmake → make」，编译产物在 build/debug/ 下。
  • 方式 2：终端手动执行（项目根目录）：

bash

运行

复制代码 
mkdir build && cd build
qmake ../QtQmlDemo.pro -spec win32-g++ "CONFIG+=debug" "CONFIG+=qml_debug"
mingw32-make -j4

默认建立空目录，如下图

执行如下命令，进行编译和连接，生成build文件

生成exe文件

双击可运行

2. 运行项目

  • 方式 1：VSCode 左侧「运行和调试」→ 选择 Qt 5.12 QML Debug (MinGW) → 点击绿色三角（F5），自动编译 + 运行。
  • 方式 2：直接双击 build/debug/QtQmlDemo.exe 运行。

3. 调试（C++ + QML 双调试）

（1）C++ 调试
  • 在 main.cpp 中点击行号左侧设置断点（红点）。
  • 按 F5 启动调试，程序停在断点处：
    • F10：单步跳过（不进入函数）。
    • F11：单步进入（进入函数）。
    • Shift+F11：单步跳出（退出函数）。
    • 左侧「变量」「监视」「调用堆栈」查看数据。
（2）QML 调试（关键）
  1. 确保 QtQmlDemo.pro 中添加：

qmake

复制代码 
QT += qml quick
CONFIG += qml_debug # 必须开启
  1. 在 main.qml 中设置断点（点击行号左侧）。
  2. 按 F5 启动调试，QML 断点会被命中，可查看 QML 变量、属性、执行流程。

六、常见问题解决

  1. 报错：qmake 不是内部命令 → 未配置 Qt 环境变量，重新添加 C:\Qt\Qt5.12.12\5.12.12\mingw73_64\bin 到 PATH，重启 VSCode。

  2. 报错：缺少 Qt5Core.dll → launch.json 中 environment 未正确配置 PATH，检查 Qt 路径是否正确。

  3. QML 断点不生效 → 确保 pro 文件加了 CONFIG += qml_debug、launch.json 加了 QT_QML_DEBUG=1、c_cpp_properties.json 加了 QT_QML_DEBUG 宏。

  4. 编译报错：undefined reference to xxx → pro 文件未添加依赖模块，如 QML 需 QT += qml quick。

  5. 智能提示失效 / 头文件报错 → 检查 c_cpp_properties.json 中 includePath 路径是否正确，重启 VSCode。

七、Release 发布（打包）

  1. 编译 Release 版：Ctrl+Shift+B 选择 make-release，产物在 build/release/。
  2. 打包 Qt 依赖（避免「缺少 DLL」）：
    • 打开 Qt 自带的 MinGW 命令行（开始菜单 → Qt 5.12.12 → MinGW 7.3.0 (64-bit)）。
    • 进入 exe 目录：cd D:\Projects\QtQmlDemo\build\release。
    • 执行 windeployqt QtQmlDemo.exe，自动拷贝所有 Qt 依赖 DLL、QML 模块、插件到当前目录。
  3. 打包后，整个 release 文件夹可直接拷贝到其他 Windows 电脑运行。
相关推荐
Quz16 小时前
QML Hello World 入门示例
qt
xcyxiner4 天前
DicomViewer (dcmtk读取dcm文件)5
qt
xcyxiner4 天前
DicomViewer (后台线程处理文件)4
qt
xcyxiner5 天前
DicomViewer (添加模型类)3
qt
xcyxiner5 天前
DicomViewer (目录调整) 2
qt
xcyxiner5 天前
dcmtk vtk vtk-dicom(gdcm) 编译(debug) v2
qt
qq_369224337 天前
Windows全系通用！ntdll.dll文件丢失、报错、闪退问题的完整排查与修复教程
windows·dll·dll修复·dll丢失·dll错误
桥田智能7 天前
桥田智能 QT-650S：面向白车身焊装的 800kg 重载快换解决方案
开发语言·qt·系统架构
森G7 天前
75、服务器源码解析---------云视频服务项目
linux·服务器·网络·c++·qt
阿米亚波7 天前
【Windows】QEMU 启动 openEuler aarch64/arm64 架构系统 + 离线软件源
linux·windows·经验分享·笔记·架构·arm
热门推荐
012026年6月AI大模型全景报告：GPT-5.6、Claude Opus 4.8、Gemini 3.5，中美AI三足鼎立谁主沉浮？022026年6月AI行业全景：从百模大战到Agent元年，这30天发生了什么？03【AI】2026 年具身智能模型和世界模型总结042026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf05Claude Code、Codex、Cursor三分天下：2026年AI编程Agent生态全景剖析06GitHub 镜像站点07【AI总结】2026年6月 主流国内外大模型总结08AI科技热点日报 | 2026年6月1日09AI科技热点日报 | 2026年6月22日10AI一周事件 · 2026-06-03 至 2026-06-09