📚 课程目录第3章开发环境搭建

3. 开发环境搭建

Qt Quick 项目能否顺利交付，第一步往往不是写代码，而是把开发环境搭对。环境搭建看似只是“装软件”，实际上涉及 Qt 版本、编译器、构建套件、设备调试链路四条主线。任何一条不匹配，都会在后续编译、部署、真机运行阶段集中爆发。本节围绕 Qt 安装、版本选择、Qt Creator 配置、模拟器与真机调试环境准备，给出一条可复用的搭建路径。

一、核心原理：Qt 环境由四层组成

理解 Qt 开发环境，关键是把它拆成四层：Qt 库版本、编译器工具链、构建套件（Kit）、目标设备。Qt Creator 只是把前三层组织起来的 IDE，真正决定“能不能编译、能不能跑”的是这四层是否一致。

Qt 库版本：决定 API、模块和 QML 运行时能力，如 Qt 5.15、Qt 6.5、Qt 6.8。
编译器工具链：桌面端常用 MSVC、MinGW、Clang；嵌入式端常用交叉编译器。
构建套件 Kit：把 Qt 版本、编译器、调试器、设备组合成一个可选项。
目标设备：桌面、Android 模拟器、Android 真机、嵌入式板卡或 iOS 设备。

提示：Qt Quick 项目对 QML 运行时和图形后端敏感，版本选择应优先看“目标平台官方支持矩阵”，而不是只看版本号新旧。

二、Qt 安装与版本选择

官方安装推荐使用 Qt Online Installer。安装时不要全选，按项目目标勾选即可。桌面开发至少选择一组桌面套件；Android 开发需额外勾选 Android 相关组件；嵌入式则需选择对应交叉编译套件或自行编译 Qt。

# 典型安装勾选示例（Qt 6.8 LTS）
Qt 6.8.0
  ├─ Desktop gcc 64-bit        # Linux 桌面
  ├─ MSVC 2022 64-bit          # Windows 桌面
  ├─ MinGW 13.1 64-bit         # Windows 轻量方案
  ├─ Android ARM64-v8a         # Android 真机/模拟器
  └─ Sources                   # 需要自定义编译时勾选

Developer and Designer Tools
  ├─ Qt Creator 15.x
  ├─ MinGW 13.1
  └─ CMake / Ninja

版本选择建议遵循三条原则：优先 LTS、与目标平台匹配、团队统一。Qt 6.8 是当前长期支持版本，适合新项目；若维护旧项目或依赖 Qt 5 专有模块，则保留 Qt 5.15。Android 与嵌入式项目要特别确认 Qt 版本是否提供对应 ABI 的预编译库。

场景	推荐 Qt 版本	编译器/工具链	说明
Windows 桌面新项目	Qt 6.8 LTS	MSVC 2022 或 MinGW 13	MSVC 与系统库兼容性更好
Linux 桌面	Qt 6.8 LTS	GCC 64-bit	注意发行版 glibc 版本
Android 应用	Qt 6.8 LTS	Android NDK + SDK	需配置 JDK 与 SDK 路径
嵌入式 Linux	Qt 6.8 / 5.15	交叉编译器	常需自行编译 Qt
旧项目维护	Qt 5.15	按原项目工具链	避免 API 迁移风险

三、Qt Creator 配置：Kit 是核心

安装完成后，打开 Qt Creator，进入 编辑 → Preferences → Kits（macOS 为 Qt Creator → Preferences）。重点检查三处：Qt Versions 是否正确指向 qmake 或 qt-cmake；Compilers 是否识别到编译器；Kits 是否把三者组合完整。

# 验证 Qt 版本与 qmake 路径
qmake -v
# 输出示例：
# QMake version 3.1
# Using Qt version 6.8.0 in /opt/Qt/6.8.0/gcc_64/lib

# 验证 CMake 构建
cmake --version
ninja --version

Qt Quick 项目建议使用 CMake 作为构建系统，Qt 6 对 CMake 支持最完整。创建项目时选择 Qt Quick Application，构建套件选择已配置好的 Kit。若 Kit 前出现黄色感叹号，说明 Qt 版本、编译器或调试器缺失，必须逐项修复后再编译。

建议为每个目标平台建立独立 Kit，例如 Desktop-MSVC2022、Android-ARM64、Embedded-ARM，避免切换时反复改配置。

四、模拟器与真机调试环境准备

Android 是 Qt Quick 最常用的移动调试平台。模拟器适合快速验证 UI 布局，真机适合验证性能、触摸、传感器和图形驱动。两者都需要先配置 JDK、Android SDK、NDK，并在 Qt Creator 的 Devices → Android 中填写路径。

# Android 环境变量示例
export JAVA_HOME=/opt/jdk-17
export ANDROID_SDK_ROOT=$HOME/Android/Sdk
export ANDROID_NDK_ROOT=$HOME/Android/Sdk/ndk/26.1.10909125
export PATH=$PATH:$ANDROID_SDK_ROOT/platform-tools

# 检查设备连接
adb devices
# 输出示例：
# List of devices attached
# emulator-5554   device
# R58M12ABCDE     device

真机调试前需在设备上开启“开发者选项”和“USB 调试”，部分厂商还需开启“USB 安装”。若 adb devices 显示 unauthorized，在手机上确认授权弹窗即可。Qt Creator 中点击“运行”时，选择 Android Kit 和目标设备，Qt 会自动完成打包、安装与启动。

五、常见误区与复盘

环境搭建阶段最常见的误区有四个：一是版本混用，桌面用 Qt 6.8、Android 用 Qt 6.5，导致 QML 模块行为不一致；二是 Kit 不完整，只配了 Qt 版本却漏配调试器，编译通过但无法断点；三是路径含中文或空格，Android SDK、NDK 路径出现中文时 adb 和 Gradle 容易失败；四是真机未授权，反复点击运行却始终部署失败。

排障顺序建议：先看 Qt Creator 的 Kit 是否绿色可用，再执行 adb devices 确认设备状态，最后查看“编译输出”和“应用程序输出”两个面板。多数问题都能在这三处定位。

复盘时建议把环境配置固化为团队文档：记录 Qt 版本、安装组件、Kit 名称、SDK/NDK 版本、环境变量和验证命令。这样新成员加入时，按文档执行即可复现，避免“我这里能跑、你那里不行”的低效沟通。环境搭建一次做对，后续 Qt Quick 的编码、调试与交付才能稳定推进。