使用 Qt Creator + MSVC 构建与调试 Lumina
约 2070 字
方案特色
许多从 Ubuntu 桌面迁移过来或习惯了 Linux 开发环境的同学,对 Qt Creator 的界面交互、快捷键、项目树视图以及 QML 智能提示更为习惯。
在 Windows 下,Qt Creator 同样可以与 MSVC 2022 64-bit 编译器完美配合,提供与 Ubuntu 下几乎完全一致的开发体验,同时无缝享受 QML 动态预览与强大的符号跳转能力。
1. 检查 Qt Creator 套件(Kit)
在通过 Qt Online Installer 安装 Qt 时,如果你勾选了 Qt Creator 与 MSVC 2022 64-bit 组件,Qt Creator 通常会自动配置好编译套件。
- 启动 Qt Creator;
- 点击顶部菜单栏 编辑 → 偏好设置(Perferences)(快捷键
Alt + T,或菜单 工具 → 选项);

- 在左侧选择 Kits(构建套件):
- Qt 版本(Qt Versions):确认已检测到
Qt 6.x.x (msvc2022_64); - 编译器(Compilers):确认 C 与 C++ 编译器已自动检测到
Microsoft Visual C++ Compiler 17.x (x86_amd64 / amd64); - 构建套件(Kits):在 Kits 列表中应存在一个标有默认图标的套件,例如
Desktop Qt 6.8.0 MSVC2022 64bit。
- Qt 版本(Qt Versions):确认已检测到

关于 Windows 下的调试器(CDB)
在 Linux 下 Qt Creator 使用 gdb 作为默认调试器;而在 Windows + MSVC 环境下,Qt Creator 依赖 Windows SDK 提供的 CDB(Command-line Debugger)。 如果在调试器一栏显示红色警告,说明你在安装 Visual Studio 时未勾选安装“Windows 调试工具”(Debugging Tools for Windows)。如果日常主要通过运行日志调试,该警告不影响正常的编译与运行(Ctrl + R)。
2. 打开 Lumina 项目
源码与 3rdParty 检查
在打开工程前,请确保已拉取源码,并已将 3rdParty 依赖压缩包(在新窗口打开) 解压至项目根目录(存在 3rdParty/tolua++ 与 3rdParty/lua 等目录,详见 环境准备与依赖安装)。
- 在 Qt Creator 欢迎界面点击 打开项目(Open Project),或点击 文件 → 打开文件或项目;
- 浏览并选中 Lumina 项目根目录下的
CMakeLists.txt(请务必选择顶层 CMakeLists,以便同时管理 Client、Medusa 与 Aurora); - 弹出 Configure Project(配置项目) 页面:
- 勾选前面准备好的
Desktop Qt 6.x MSVC2022 64bit套件; - 展开构建配置列表,建议勾选 Release(首次体验建议优先选 Release);
- 点击右下角的 Configure Project 按钮。
- 勾选前面准备好的
3. 配置 CMake 工具链与 Qt 路径
CMAKE_TOOLCHAIN_FILE 用于接入 vcpkg 安装的依赖;CMAKE_PREFIX_PATH 用于指定 Qt 等依赖的安装前缀。填好 vcpkg 工具链后,有时仍需要显式设置 Qt 的 CMAKE_PREFIX_PATH,例如 Qt 安装在自定义目录、电脑上有多个 Qt 版本,或配置时找不到正确的 Qt6。
- 在 Qt Creator 左侧点击 项目(Projects)(
Ctrl + 5),进入当前 MSVC Kit 的 Build(构建设置)。 - 找到 CMake → Initial Configuration(初始配置),检查或添加下表变量。已有同名项时直接修改,路径换成自己的实际安装位置。
- 点击 Re-configure with Initial Variables / Parameters(使用初始参数重新配置);如果修改的是 Current Configuration(当前配置),点击 Run CMake / Apply Configuration Changes。不同版本的按钮名称可能略有区别,参见 Qt Creator CMake 设置说明。
| 名称(Key) | 类型 | 示例值 | 用途 |
|---|---|---|---|
CMAKE_TOOLCHAIN_FILE | File / FILEPATH | C:/vcpkg/scripts/buildsystems/vcpkg.cmake | 接入 vcpkg 工具链,应在首次配置时设置 |
VCPKG_TARGET_TRIPLET | String | x64-windows | 与前文安装依赖的目标架构保持一致 |
CMAKE_PREFIX_PATH | String | C:/Qt/6.8.0/msvc2022_64 | 指定与当前 Kit 匹配的 Qt 套件前缀;Kit 已传入正确值时可保留 |
USE_CUDA_MODULE | Boolean / BOOL | OFF | 首次纯 CPU 构建时关闭;已配置 CUDA 后再按需开启 |
USE_ROCM_MODULE | Boolean / BOOL | OFF | Windows 本教程保持关闭;纯 CPU 时两个 GPU 后端均关闭 |
如何填写 CMAKE_PREFIX_PATH
填写安装 Qt 时记下的 msvc2022_64 套件目录,例如:
C:/Qt/6.8.0/msvc2022_64不要填 Qt 安装根目录、版本目录或 bin 目录。例如应存在:
C:/Qt/6.8.0/msvc2022_64/lib/cmake/Qt6/Qt6Config.cmakeCMAKE_PREFIX_PATH 是安装前缀列表,CMake 会在前缀下继续查找 lib/cmake 等子目录。仅有一个 Qt 时直接填写上述套件目录;已有其他必要依赖前缀时,使用英文分号 ; 分隔并保留它们。此处是在 CMake 表格中填写值,无需加引号或 -D。
Qt6_DIR 是另一种更具体的定位方式,填写的是 C:/Qt/6.8.0/msvc2022_64/lib/cmake/Qt6。一般优先使用 CMAKE_PREFIX_PATH,无需同时手动设置二者;若已有 Qt6_DIR 或 Qt6*_DIR 缓存指向旧 Qt,应清理旧配置,避免混用版本。
修改后仍找到旧 Qt 或旧依赖
工具链与 triplet 应在第一次 CMake 配置前设置,详见 vcpkg CMake 集成说明。如果项目已经自动配置过,或你切换了 Kit、工具链、triplet、Qt 版本,建议为该 Kit 使用新的独立构建目录,并确认初始配置中保留了这些参数后再运行 CMake。只执行“清理构建”不会清除旧的 CMake 缓存。
配置日志出现 Configuring done、Generating done 后,检查 Qt6_DIR 是否落在选定套件中。若路径正确但仍缺少 Core5Compat、SerialPort 或 WebSockets,请在 MaintenanceTool 中为同一版本、同一 MSVC 套件补装组件,路径参数不能代替组件安装。
其他关键参数
- 构建类型:日常仿真优先选择
Release。Ninja 等单配置生成器使用CMAKE_BUILD_TYPE=Release;Visual Studio 等多配置生成器在构建时选择Release,仅设置CMAKE_BUILD_TYPE不会切换实际配置。 - 场地:默认
USE_DIV_A=OFF、USE_DIV_B=ON;使用 A 场时同时设置USE_DIV_A=ON、USE_DIV_B=OFF,修改后重新构建。 - 技术挑战赛:
IS_TECH默认OFF,仅在对应比赛模式下开启。 - 3D 视图:
LUMINA_ENABLE_FIELD3D默认OFF;开启前需为当前 Qt 套件安装同版本 Qt Quick 3D。 - CUDA:启用
USE_CUDA_MODULE前检查驱动、CUDA Toolkit 与 MSVC 的兼容性;CUDA_TARGET_ARCH控制目标 GPU 架构,通常为native。不要同时开启 CUDA 与 ROCm。
完整参数说明和计算后端选择见 配置 Lumina,其中 Ubuntu 的 GCC 套件路径需换成本文的 MSVC 套件路径。
4. 运行环境与工作目录检查
Lumina 的可视化客户端和策略引擎需要读取 ZBin/ 目录下的配置文件(如 zss.ini)与 Lua 策略脚本。
- 在左侧导航栏点击 项目(Projects) → Run(运行设置);
- 在顶部的 Run configuration(运行配置) 下拉菜单中,选择你想要运行的目标:
Client:可视化客户端;Medusa:核心决策引擎;Aurora:独立串口调车工具。
- 检查 Working directory(工作目录):
- 工程的
VS_DEBUGGER_WORKING_DIRECTORY用于 Visual Studio 调试,Qt Creator 的运行工作目录仍需在此检查; - 请确认或手动将其浏览设置为项目源码根目录下的
ZBin目录(例如D:\robocup\lumina\ZBin)。
- 工程的
5. 构建与启动运行
- 编译项目:点击左下角的大锤子图标,或者按快捷键
Ctrl + B。 Qt Creator 会启动多线程并行构建,并自动触发后置构建命令:- 执行
windeployqt将 Qt6 的界面与网络运行库拷贝至ZBin/; - 自动复制 vcpkg 编译的动态库(如
libprotobuf.dll)至ZBin/。
- 执行
- 启动运行:点击左下角的绿色三角形播放按钮,或者按快捷键
Ctrl + R。 - 切换运行程序: 在 Qt Creator 左下角的目标选择器(电脑小图标)上点击,可以自由在
Client、Medusa或Aurora之间切换当前激活的构建和运行目标。
6. 开发技巧与小结
- QML 界面热调试:在
Client/目录下修改 QML 样式后,由于 QML 属于解释型脚本,在不重新编译 C++ 的情况下也能极快完成界面迭代。 - 双平台平滑过渡:你在 Windows 上使用 Qt Creator 编辑的文件格式与编码与 Ubuntu 完全一致(统一 UTF-8 编码与 LF 换行规则),Git 提交不会产生杂乱的换行差异。
- 双进程联调:在日常开发中,可以先在 Qt Creator 中按
Ctrl + R运行Client,然后在 Client 的控制面板中直接点击启动 Medusa,或者分别在两个终端/窗口中独立观察两者通信。