Qt5 迁移 Qt6 完整注意事项（模块变化、类改名、接口变更）

Qt6 是架构重构版本移除大量废弃 API、拆分模块、修改类名与接口。本文整理高频变更点适合商用项目、老项目批量迁移。建议迁移路径Qt5.12/5.15 → Qt6.2 LTS长期支持版一、模块整体变化最容易编译报错1. Widgets 模块独立必加Qt5widgets模块默认隐式加载。Qt6必须手动显式添加qmake(.pro)proQT widgetsCMakecmakefind_package(Qt6 REQUIRED COMPONENTS Core Widgets) target_link_libraries(App PRIVATE Qt6::Widgets)2. 模块拆分与重命名表格功能Qt5 模块Qt6 模块说明多媒体multimediamultimedia部分子接口调整串口serialportserialport基本兼容脚本script彻底移除不再支持WebKitwebkit移除改用webengine旧网页控件淘汰图形动画animation并入 core/widgets无需单独添加3. 废弃模块Qt6 彻底删除Qt Script、Qt WebKit、Qt Quick 1 系列、Qt XML Patterns解决方案替换为 Qt WebEngine、原生 QML、第三方库。二、类与头文件变更1. 容器、字符串相关隐式头文件移除Qt5 部分类不用手动 includeQt6 必须显式包含头文件cpp运行// Qt6 必须手动添加 #include QString #include QList #include QVector #include QMap #include QFile2.QRegExp正则表达式 彻底废弃Qt5QRegExpQt6推荐使用QRegularExpression迁移示例cpp运行// Qt5 QRegExp rx(\\d); // Qt6 QRegularExpression rx(\\d);3.QAction、菜单栏部分接口调整部分默认构造函数、图标接口参数变化。4. 图形类QPaint相关废弃旧式绘制函数移除低层级、不安全绘制接口统一使用新绘图路径。三、枚举、命名空间变化大量枚举从全局移入对应类作用域Qt5 写法报错cpp运行btn-setCheckable(true); if(btn-checkState() Checked) // Qt6 报错Qt6 正确写法cpp运行if(btn-checkState() Qt::Checked)Qt::WindowFlags、Qt::Alignment等严格类型检查隐式转换收紧。四、信号槽与函数接口变更1. 旧风格信号槽SIGNAL/SLOT宏仍可用但不推荐Qt6 更强制推荐函数指针写法编译期类型检查更严格。2. 重载函数连接写法统一Qt5/Qt6 统一使用QOverloadQt6 对重载检查更严格。cpp运行connect(btn, QOverloadbool::of(QPushButton::clicked), this, MainWindow::slot);3. 移除emit关键字仍兼容但不建议使用emit本质是空宏Qt6 不再推荐书写。五、废弃函数与接口高频踩坑1.QString::ascii()、QString::fromAscii()移除替换fromLatin1()/toLatin1()cpp运行// Qt5 废弃 QString::fromAscii(test); // Qt6 QString::fromLatin1(test);2.QDateTime::currentMSecsSinceEpoch()废弃替换QDateTime::currentMSecsSinceEpoch()→ 改用QElapsedTimer/ 新时间 API。3.旧式文件、IO 相关辅助函数清理。六、编译与工程配置差异C 版本要求Qt6 默认要求C17建议工程全局开启proCONFIG c17cmakeset(CMAKE_CXX_STANDARD 17)编译器要求WindowsMSVC 2019 / MinGW 新版本LinuxGCC 7老旧编译器无法编译 Qt6。资源系统Qt6 支持新资源系统qt_add_resources旧 qrc 完全兼容。七、QML / Qt Quick 迁移Qt Quick Controls 1 彻底移除必须升级为Qt Quick Controls 2QML 模块版本号升级如import QtQuick 6.0部分视觉控件属性、样式接口调整。八、迁移步骤建议工程级本地 Qt5.15 先修复所有警告替换废弃接口切换编译套件为 Qt6逐步解决编译错误优先补全头文件、补充widgets模块替换QRegExp、fromAscii等淘汰接口测试信号槽、UI 布局、数据库、网络功能全平台Windows/Linux回归测试。小结Qt5 → Qt6 核心工作量补全模块与头文件、替换废弃 API、修正枚举作用域、升级 C 标准。纯 Widget 项目迁移成本较低使用旧 QML、Script、WebKit 的项目需要重点改造。