使用 Visual Studio 2022 构建与调试 Lumina
约 1915 字
方案特色
在 RoboCup 小型组开源社区中,上海交通大学 SRC 战队(SJTU-SRC) 长期在 Windows 平台上保持高效的开发迭代,其官方教程主推以 Visual Studio 2022 / MSVC 作为核心集成开发与编译工具链。
Visual Studio 拥有工业级强大的 MSVC 编译器、直观的可视化工程管理面板、强大的内存诊断与多进程调试器。本教程效仿上交 SRC 的工程管理实践,详细介绍如何在 VS2022(及 VS Code + MSVC 环境)中配置并运行 Lumina。
1. 准备工作检查
在开始本章节前,请确保你已经完成了前置依赖的准备(详见 环境准备与依赖安装):
- 已安装 Visual Studio 2022 且包含“使用 C++ 的桌面开发”工作负荷;
- 已通过 vcpkg 安装好
protobuf,eigen3,ode,yaml-cpp,fmt,zstd等三方库; - 已通过 Qt Online Installer 安装好 Qt 6 MSVC 2022 64-bit;
- 已克隆 Lumina 源码仓库到本地硬盘;
- 核心必做:已下载并解压 3rdParty 依赖压缩包(在新窗口打开) 到 Lumina 源码根目录(确保
lumina/3rdParty/tolua++等目录就位,详见 环境准备与依赖安装)。
2. 方式一:生成 Visual Studio 解决方案(.sln 推荐)
对于大型工程和初学者来说,生成并打开原生的 .sln 解决方案文件是最稳定、排错最直观的方式。
2.1 执行 CMake 生成解决方案
打开 PowerShell(或 VS 自带的 Developer PowerShell for VS 2022),切换到 lumina 根目录下,执行以下命令:
# 1. 创建独立的构建目录
mkdir build-windows-vs2022
cd build-windows-vs2022
# 2. 调用 CMake 生成 VS2022 解决方案工程
# 请根据你的实际安装路径替换 vcpkg.cmake 和 Qt msvc2022_64 路径
cmake .. `
-G "Visual Studio 17 2022" `
-A x64 `
-DCMAKE_TOOLCHAIN_FILE="C:/vcpkg/scripts/buildsystems/vcpkg.cmake" `
-DCMAKE_PREFIX_PATH="C:/Qt/6.8.0/msvc2022_64" `
-DUSE_CUDA_MODULE=OFF `
-DUSE_ROCM_MODULE=OFF启用 CUDA 的情况
如果你拥有 NVIDIA 独立显卡并安装了 CUDA Toolkit,可将参数更改为: -DUSE_CUDA_MODULE=ON -DCUDA_TARGET_ARCH=native
配置成功后,终端将输出类似如下信息:
-- Lumina Qt auto-detect: explicit Qt prefix already set, skipping
-- Found Protobuf: ...
-- Found Eigen3: ...
-- Found YAML_CPP: ...
-- Configuring done
-- Generating done
-- Build files have been written to: .../lumina/build-windows-vs20222.2 在 Visual Studio 2022 中打开项目
在 build-windows-vs2022 目录下,双击打开生成好的 lumina.sln。
在右侧的 解决方案资源管理器 中,可以看到 Lumina 的清晰工程架构:
- Client:Qt6 QML 可视化客户端界面
- Medusa:核心决策与运动控制策略引擎
- Aurora:串口调车工具
- Zrazy:底盘 WiFi 通信控制模块
- ALL_BUILD 与 ZERO_CHECK:CMake 自动化管理工程
3. 方式二:直接“打开文件夹”(VS 原生 CMake 模式)
VS2022 原生支持直接打开含有 CMakeLists.txt 的文件夹。如果你偏好轻量、不生成外部 .sln 的工作流:
打开 Visual Studio 2022,点击 文件 → 打开 → 文件夹,选择 Lumina 的项目根目录。
VS 会自动检测到顶层的
CMakeLists.txt并尝试启动 CMake 配置。首次配置时,选择识别到的 Visual Studio MSVC 编译器:
点击顶部菜单栏的 项目 → Lumina 的 CMake 设置,或编辑自动生成的
CMakeSettings.json(或CMakePresets.json),在 CMake 命令行参数中加入:{ "name": "x64-Release", "generator": "Visual Studio 17 2022", "configurationType": "Release", "inheritEnvironments": [ "msvc_x64_x64" ], "variables": [ { "name": "CMAKE_TOOLCHAIN_FILE", "value": "C:/vcpkg/scripts/buildsystems/vcpkg.cmake" }, { "name": "CMAKE_PREFIX_PATH", "value": "C:/Qt/6.8.0/msvc2022_64" }, { "name": "USE_CUDA_MODULE", "value": "OFF" } ] }保存后,VS2022 会自动重新生成 CMake 缓存与智能感知索引。
4. 方式三:使用 VS Code + MSVC 编译插件(上交常用)
不少同学平时更习惯在 VS Code 中编写代码与管理 Git。在 Windows 下同样可以使用 VS Code + CMake Tools 配合已安装的 Visual Studio 2022 编译器:
在 VS Code 中安装 CMake Tools 扩展插件:

点击左侧扩展栏中的 CMake,选择 MSVC 2022 x64 作为编译器 Kit,并点击“配置”:

在 VS Code 设置(
settings.json)中添加 CMake 参数:{ "cmake.configureArgs": [ "-DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake", "-DCMAKE_PREFIX_PATH=C:/Qt/6.8.0/msvc2022_64", "-DUSE_CUDA_MODULE=OFF" ] }
5. 关键配置与构建运行
5.1 选择构建配置(强烈推荐 Release)
在顶部工具栏的配置选择下拉框中,将构建类型选择为 Release(或 RelWithDebInfo)。
为什么不推荐日常用 Debug 混编?
- 性能要求:Lumina 策略引擎与视觉预测在实时比赛中需要极高的循环频率,Debug 模式下的无优化代码可能导致仿真丢帧或卡顿。
- DLL 统一性:
Client.exe与Medusa.exe共享输出在ZBin/目录下。CMake 的依赖部署脚本会自动为 Release 配置拷贝优化版 DLL。如果一个工程编 Debug、另一个编 Release,极易发生 C++ 运行时库版本不一致导致的闪退。
5.2 编译项目
在解决方案资源管理器中:
- 右键点击 ALL_BUILD,选择 生成(快捷键
Ctrl + Shift + B)。 - CMake 编译系统将并行编译各个组件,并在编译后自动执行后处理步骤:
- 自动生成 Protobuf 消息序列化代码;
- 调用
tolua++解析并生成 Lua 导出绑定; - 调用
windeployqt将 Qt6 的运行时 DLL 及 QML 插件完整复制到ZBin/; - 拷贝 vcpkg 依赖的三方 DLL(如
libprotobuf.dll,yaml-cpp.dll)到ZBin/。
5.3 设置启动项与调试工作目录
Lumina 的配置文件(zss.ini)、策略脚本目录(lua_scripts/)、阵型与战术配置全部存放在 ZBin/ 目录下。
- 在解决方案中,CMake 脚本已默认将
Client设置为启动工程。 - 右键点击 Client → 属性 → 展开 配置属性 → 调试:
- 命令参数:可留空;
- 工作目录:确认为
$(SolutionDir)..\ZBin或$(ProjectDir)..\ZBin(绝对路径对应项目根目录下的ZBin)。
按键盘快捷键 F5(启动调试)或 Ctrl + F5(不调试直接启动),Lumina 可视化客户端即可在 Windows 下流畅启动!
6. 多进程联合调试(Client + Medusa)
在实际赛前调试中,通常由 Client 界面拉起 Medusa 策略引擎,或者单独启动 Medusa 查看策略日志输出。
在 Visual Studio 中,你可以体验强大的多进程联调能力:
设置多启动项目:
- 右键点击解决方案根节点,选择 属性;
- 在左侧选择 常用属性 → 启动项目;
- 勾选 多个启动项目,将
Client和Medusa的操作均设置为 启动; - 点击应用。此时按 F5,VS2022 会同时启动界面与策略端,并在两个进程中同时命中你的断点!
附加到进程(Attach to Process):
- 如果你已经在 Client 界面内点击启动了 Medusa,在 VS2022 菜单栏点击 调试 → 附加到进程(快捷键
Ctrl + Alt + P); - 在进程列表中搜索
Medusa.exe并双击附加; - 之后在 C++ 决策逻辑(如
src/Algorithm/或src/Strategy/)打下断点,小车在仿真器中跑位时即可随时中断分析。
- 如果你已经在 Client 界面内点击启动了 Medusa,在 VS2022 菜单栏点击 调试 → 附加到进程(快捷键
7. Windows 平台排坑指南
1. 源码中文字符与编译乱码
- 表现:MSVC 报错
C4819: 该文件包含在当前代码页中不能表示的字符。 - 解决:Lumina 的根目录
CMakeLists.txt中已经强制注入了/utf-8编译参数(add_compile_options("$<$<COMPILE_LANGUAGE:C,CXX>:/utf-8>")),确保源码统一使用 UTF-8 编码识别,无需修改 Windows 系统语言区域。
2. 缺少 Qt 或三方 DLL 报错(0xc000007b / 找不到指定模块)
- 表现:直接在资源管理器双击
ZBin\Client.exe提示缺少Qt6Core.dll或libprotobuf.dll。 - 解决:请确认是否在 Visual Studio 中完整生成了 Client 目标。只要通过 VS 成功构建过一次 Client,CMake 内置的
windeployqt与 DLL 自动复制机制就会把所有依赖补全在ZBin/目录下。
贡献者
更新日志
70e77-Windows教程, Git LFS 追踪于