1. 课程导入
欢迎进入《Qt Quick项目交付实战》。很多开发者已经能够使用 QML 编写界面、用 C++ 实现业务逻辑，也能在 Qt Creator 中顺利运行一个 Demo，但当项目真正要交付给客户、部署到现场设备、面对不同分辨率屏幕、不同操作系统、不同网络环境时，问题才真正开始暴露。本课程关注的不是“如何写出一个能跑的 Qt Quick 程序”，而是“如何把一个 Qt Quick 项目稳定、可维护、可验证地交付出去”。
换句话说，本课程的核心命题是：从可运行到可交付之间，究竟还差哪些工程化工作？ 这些工作包括构建配置、资源管理、性能优化、跨平台打包、安装部署、日志诊断、版本管理、自动化测试与交付验收。它们共同构成了一条完整的交付链路。
一、学习目标：从“会写”到“能交付”
完成本课程后，你应当具备以下能力：
- 能够为一个 Qt Quick 项目设计清晰的工程结构，区分 QML 前端、C++ 后端、资源文件、第三方依赖与构建脚本。
- 能够使用 CMake 或 qmake 组织多模块项目，并理解 release、debug、profile 等构建配置的差异。
- 能够将 QML 资源通过 Qt Resource System 或外部资源目录进行管理，并处理热更新与版本兼容问题。
- 能够针对启动速度、渲染帧率、内存占用等指标进行基础性能分析与优化。
- 能够完成 Windows、Linux、Android 等平台的打包与部署，并处理动态库、插件与运行时依赖。
- 能够建立日志、崩溃捕获与现场诊断机制，使交付后的系统具备可观测性。
- 能够制定交付清单，完成版本冻结、安装验证、回滚方案与验收文档。
一句话总结学习目标：让 Qt Quick 项目具备“可构建、可测试、可部署、可诊断、可维护”的交付属性，而不仅仅是“能运行”。
二、核心概念：交付视角下的 Qt Quick 工程
在进入具体技术之前，需要先建立几个贯穿全课程的核心概念。
1. 交付物（Deliverable）：最终交给客户或部署到现场的东西，通常不是源代码，而是安装包、可执行目录、镜像、APK 或容器镜像。交付物的完整性决定了项目能否被真正使用。
2. 运行时依赖（Runtime Dependency）：Qt Quick 应用依赖 Qt 核心库、QML 模块、平台插件、图形驱动、字体、图像格式插件等。缺少任何一个，程序都可能在目标机器上无法启动或显示异常。
3. 资源与代码的边界：QML、图片、字体、翻译文件属于资源；C++ 业务逻辑、第三方库属于代码。资源可以独立更新，代码需要重新编译。清晰的边界是热更新和模块化交付的前提。
4. 构建配置（Build Configuration）：同一份代码在不同构建配置下会产生不同产物。Release 优化性能，Debug 便于排查，Profile 用于分析。交付必须明确使用哪种配置。
5. 可观测性（Observability）：交付后的系统需要日志、指标和崩溃报告，否则现场问题只能靠猜测。可观测性是交付质量的重要保障。
下面这张图展示了 Qt Quick 项目从源码到交付物的整体框架与关键环节，它也是本课程后续章节的路线图。
三、整体框架：五个阶段与一条闭环
上图把 Qt Quick 项目交付拆解为五个阶段，它们不是孤立的，而是通过反馈闭环连接在一起。
| 阶段 | 关键任务 | 典型产出 | 常见风险 |
|---|---|---|---|
| ① 源码与资源 | 工程结构设计、QML/C++ 边界划分、资源组织 | 可维护的源码树、资源清单 | 资源散落、模块耦合严重 |
| ② 构建与配置 | CMake/qmake 配置、构建类型选择、资源编译 | 可复现的构建产物 | 本地能编、CI 失败、配置漂移 |
| ③ 打包与部署 | 依赖收集、平台打包、安装脚本 | 安装包、绿色目录、APK | 缺库、缺插件、路径错误 |
| ④ 运行与诊断 | 日志、崩溃捕获、性能采集 | 日志文件、崩溃报告、指标 | 现场无日志、问题无法复现 |
| ⑤ 验收与维护 | 交付清单、版本冻结、回滚方案 | 验收文档、版本记录 | 版本混乱、无法回退 |
这条闭环的意义在于：现场诊断数据会反哺构建与优化，验收结果会推动下一轮迭代。交付不是一次性动作，而是一个持续循环的工程过程。
四、交付流程概览：一次典型交付要做什么
下面用一个简化的命令序列展示一次典型交付中构建与打包的关键步骤，帮助建立整体印象。
# 1. 配置构建目录（Release）
cmake -S . -B build/release -DCMAKE_BUILD_TYPE=Release
# 2. 编译并生成可执行文件
cmake --build build/release --config Release -j 8
# 3. Windows 平台收集 Qt 运行时依赖
windeployqt --release --qmldir qml build/release/App.exe
# 4. Linux 平台收集依赖并生成 AppImage
linuxdeployqt build/release/App -qmldir=qml -appimage
# 5. 校验交付目录结构
# App.exe / App
# ├── Qt5Core.dll / libQt5Core.so
# ├── platforms/qwindows.dll
# ├── qml/ (QML 模块)
# └── resources/ (图片、字体、翻译)
提示：交付目录中的 qml 子目录必须与代码中 import 的模块路径一致。很多“本地能跑、现场白屏”的问题，根源就是 QML 模块没有被正确收集。
五、案例场景：一个真实交付问题的复盘
某工业控制项目使用 Qt Quick 开发触摸屏界面，开发机上运行流畅，但部署到现场工控机后出现两个问题：启动时提示“Could not find the Qt platform plugin windows”，以及界面中文字体显示为方框。
复盘发现：第一，打包时只复制了可执行文件，没有使用 windeployqt 收集 platforms 插件；第二，目标机器缺少开发机上的中文字体，而项目使用了系统字体而非内嵌字体。修复方式是在构建阶段加入依赖收集脚本，并将字体文件通过 Qt Resource System 嵌入程序。
这个案例说明：交付问题往往不是代码逻辑问题，而是环境与依赖问题。 本课程后续章节会逐一展开这些工程化细节。
常见误区：把“在我电脑上能运行”当作交付标准。真正的交付标准是“在目标环境中可重复安装、可稳定运行、可诊断问题、可回滚版本”。
六、本课程的知识地图
围绕上述五个阶段，本课程将依次覆盖：工程结构与模块划分、CMake 构建体系、QML 资源管理、性能分析与优化、跨平台打包部署、日志与崩溃诊断、自动化测试、版本管理与交付验收。每一章都会围绕一个可落地的工程问题展开，并给出可复用的配置、脚本与检查清单。
学习本课程时，建议你准备一个真实的 Qt Quick 项目作为练习对象，跟随章节逐步完善它的构建、打包与诊断能力。只有把知识落到自己的项目上，交付能力才会真正形成。