Qt 6 是一个主版本，将一个真实的 Qt 5 应用迁移到它，远不止是重新编译那么简单。框架经过了模块化，构建系统转向了 CMake，部分 API 被移除或替换，模块也被移动到别处。这些都不是无法克服的，但一次成功的 Qt 5 到 Qt 6 迁移是被规划出来的，而不是碰运气得来的。本指南介绍了发生了哪些变化，以及在 2026 年应如何着手这次迁移。
要点速览
- Qt 6 是一个带有破坏性变更的主版本发布：模块化的结构、作为主要构建系统的 CMake、被移除和替换的 API，以及被重新安置的模块
- 将构建系统从 qmake 转到 CMake，往往是单项工作量最大的部分
- 在可能的情况下增量迁移，利用 Qt 提供的兼容性辅助工具，并依靠你的测试套件来捕获回归
- 由于 Qt 5 已过了活跃支持期，停留在它上面是一种不断累积的风险，因此要有意识地规划这次迁移
为什么要迁移到 Qt 6
Qt 5 已到达其活跃支持生命周期的终点，因此新功能、修复以及（至关重要的）安全更新都流向了 Qt 6。除了保持最新之外，Qt 6 还带来了现代化的 C++ 基线、改进的图形栈，以及对 QML 和工具链的持续投入。停留在 Qt 5 上是一笔缓慢增长的负债，而非一个稳定的落脚点。
实际上有哪些变化
构建系统：CMake 优先。 Qt 6 让 CMake 成为主要的构建系统。qmake 依然存在，但投入与文档如今都集中在 CMake 上。对许多项目而言，从 qmake 到 CMake 的转换是迁移中最大的部分。
模块化。 Qt 经过了重构，一些功能被移出了核心模块，或被移入了独立的模块。依赖隐式可用类的代码可能需要显式的模块依赖，而某些部分现在位于 Qt 5 Compatibility module 中。
被移除和更改的 API。 已弃用的 Qt 5 API 被移除，一些类和函数被替换或更改了签名。常见的涉及领域包括容器、字符串处理、QRegExp（被 QRegularExpression 取代）、枚举，以及图形和多媒体栈的部分内容的相关变化。
QML 改进。 QML 及其相关工具在 Qt 6 中得到了发展；重度使用 QML 的应用会从中受益，但可能需要做出调整。
如何规划 Qt 5 到 Qt 6 的迁移
- 先升级到最新的 Qt 5。 迁移到最终的 Qt 5 发行版，并在那里修复所有弃用警告。Qt 提供了兼容性辅助工具，让你可以在切换主版本之前先清除大多数弃用项。
- 将构建转换到 CMake。 如果你使用的是 qmake，请把 CMake 转换作为一个独立的工作流来规划；它往往是最大的一项投入。
- 更新模块依赖。 为所有被移动的部分添加显式依赖，并为那些你无法立即替换的 API 引入 Qt 5 Compatibility module。
- 修复被移除和更改的 API。 处理由被移除 API 引发的编译器错误，将它们替换为 Qt 6 中的等价物。
- 依靠你的测试。 一套稳固的自动化测试套件正是让这项工作变得安全的关键；它能捕获编译器无法发现的行为回归。
- 在可能的情况下增量迁移。 分阶段处理模块或组件，而不是尝试一次性的大爆炸式切换，对于大型应用尤其如此。
常见陷阱
- 低估构建系统的转换。 团队为 API 修复安排了预算，却忘了 CMake 的迁移往往更大。
- 第三方依赖。 一个尚未适配 Qt 6 的依赖可能会阻塞整个迁移；要尽早审查它们。
- 行为变化，而不仅仅是编译错误。 有些变更能顺利编译，但行为却不同；只有测试和 QA 才能捕获这些。
- 跳过最终的 Qt 5 步骤。 在没有先在最后一个 Qt 5 上清除弃用项的情况下直接跳到 Qt 6，会让迁移难度大大增加。
关键要点
- Qt 6 是一个带有真实破坏性变更的主版本；应把迁移当作一个有规划的项目来对待，而非一次重新编译。
- 从 qmake 到 CMake 的转换常常是单项工作量最大的任务。
- 先升级到最终的 Qt 5，在切换之前清除弃用警告，然后再修复被移除的 API 和被重新安置的模块。
- 尽早审查第三方依赖，并依靠你的测试套件来捕获行为回归。
为你的 Qt 迁移获取专家帮助
有了深厚的框架经验，Qt 5 到 Qt 6 的迁移会更快、更安全。如果你需要聘请一名 Qt 开发者 ，Mecanik 在 Qt 4、5 和 6 上拥有超过 15 年的 Qt 经验，涵盖 Qt Widgets 和 QML 应用，以及具备完整源码所有权的 Qt 5 到 Qt 6 迁移。对于在 Qt 之外还有大量 C++ 组件的项目，一位可聘请的 C++ 开发者 能提供帮助。另请参阅使用 Qt 和 QML 构建跨平台桌面应用 指南。
常见问题（FAQ）
从 Qt 5 迁移到 Qt 6 难吗？ 这是一次带有破坏性变更的主版本迁移，所以不仅仅是重新编译，但只要做好规划就非常可控。主要的工作是将构建系统迁移到 CMake、更新被重新安置的模块，以及替换被移除的 API，而测试则可防范回归。
为了 Qt 6，我必须从 qmake 切换到 CMake 吗？ qmake 在 Qt 6 中仍然可用，但 CMake 是主要的、积极开发的构建系统，也是文档和投入所在。为了长期的可维护性，推荐转换到 CMake，而且它往往是迁移中最大的部分。
我为什么应该离开 Qt 5？ Qt 5 已到达其活跃支持的终点，因此新功能、错误修复和安全更新都会进入 Qt 6。停留在 Qt 5 上是一种不断累积的风险，尤其是在安全方面，这正是有规划的迁移值得进行的原因。
什么是 Qt 5 Compatibility module？ 它是一个 Qt 6 模块，提供了从核心中移除的 API，让你可以增量迁移。它让你在朝着完整的 Qt 6 等价物推进的同时，继续使用某些 Qt 5 时代的 API，而不必一次性替换所有内容。
我应该如何着手一次大型的 Qt 迁移？ 先升级到最终的 Qt 5 发行版并清除弃用警告，将构建转换到 CMake，更新模块依赖，然后修复被移除的 API，分阶段迁移并依靠你的自动化测试。尽早审查第三方依赖对 Qt 6 的支持情况。
评论