打包发布与部署
把程序变成可交付安装包,覆盖三平台与合规要点
#发布到底要做什么
前面六章你写的程序都能"在我机器上跑",但拷给别人往往会闪退或报错。原因很简单:Qt 程序依赖一堆动态库(Qt6Core.dll、Qt6Widgets.dll)、插件(平台插件 qwindows.dll、图像插件、样式插件)、以及 QML 模块(QML 应用还需要 QtQuick/ 目录下的上百个文件)。目标机器上没有这些,程序就起不来。
打包发布要完成四件事:收集依赖 → 裁掉不需要的 → 做成安装包 → 装到目标机验证。其中"验证"最容易被跳过,也最容易出事:必须在一台干净的机器(或虚拟机)上测试,因为你自己的开发机上 Qt 的 bin 目录往往在 PATH 里,掩盖了大量缺失依赖。
#Windows:windeployqt
Qt 自带 windeployqt 工具,它会扫描你的 exe,把所需的 DLL、插件、QML 模块、翻译文件全部复制到 exe 所在目录。
# 1. 先编译 Release 版本(Debug 版依赖的 DLL 带 d 后缀,且不能分发)
cmake -S . -B build-release -DCMAKE_BUILD_TYPE=Release
cmake --build build-release --config Release
# 2. 进入输出目录执行部署(务必用与构建时相同的 Qt 套件的 windeployqt)
cd build-release
C:/Qt/6.6.0/msvc2019_64/bin/windeployqt.exe MyApp.exe --qmldir ../qml
# 常用参数
# --qmldir <dir> 扫描 QML 源码,带上真正用到的 QML 模块(QML 项目必加)
# --no-translations 不复制 qt_*.qm 翻译文件,可省几十 MB
# --no-system-d3dcompiler 旧系统相关的 DX 组件,现代系统可去掉
# --compiler-runtime 顺带复制 MSVC 运行库(配合 vcredist 二选一)MSVC 与 MinGW 的区别:MSVC 编译的程序依赖 VC++ 运行库(vcruntime140.dll、msvcp140.dll),windeployqt --compiler-runtime 会复制它们,但更规范的做法是让用户安装 Microsoft Visual C++ Redistributable(或直接把它打进安装包静默安装)。MinGW 编译的程序则依赖 libgcc_s_seh-1.dll、libstdc++-6.dll、libwinpthread-1.dll,windeployqt 通常会自动带上,漏了就手动补。
部署完成后建议用开源工具 Dependencies(替代老旧的 Dependency Walker)打开 exe 复查一遍,显示为红色的条目就是仍然缺失的库,需要手动补进目录。这一步能提前发现 windeployqt 扫描不到的间接依赖,比如你自己引入的第三方 DLL。
部署完的目录结构大致是:
release/
├── MyApp.exe
├── Qt6Core.dll Qt6Gui.dll Qt6Widgets.dll Qt6Quick.dll ...
├── platforms/qwindows.dll # 平台插件,缺了会报 "This application failed to start
│ # because no Qt platform plugin could be initialized"
├── styles/qwindowsvistastyle.dll # Widgets 视觉样式
├── imageformats/qjpeg.dll qsvg.dll # 图片格式
├── qml/QtQuick/ QtQuick/Controls/ ... # QML 项目专有
└── translations/(可选)平台插件缺失是 Windows 上最高频的发布故障,表现是双击无反应或弹一个英文对话框。记住目录名必须是 platforms(复数),且相对 exe 而言。
#Windows:制作安装包
推荐 Inno Setup(脚本简单、体积小、中文支持好)或 NSIS(更灵活、更古老)。下面是 Inno Setup 脚本的核心片段:
; setup.iss
#define MyAppName "数据监控仪表盘"
#define MyAppVersion "1.2.0"
#define MyAppPublisher "我的公司"
#define MyAppExeName "Dashboard.exe"
[Setup]
AppId={{8F2A1B3C-4D5E-6F70-8A9B-0C1D2E3F4A5B}
AppName={#MyAppName}
AppVersion={#MyAppVersion}
DefaultDirName={autopf}\{#MyAppName}
DefaultGroupName={#MyAppName}
OutputDir=installer
OutputBaseFile=Dashboard_Setup_{#MyAppVersion}
Compression=lzma2/ultra64 ; 压缩率高,Qt 程序通常能压到 1/3
SolidCompression=yes
ArchitecturesInstallIn64BitMode=x64
PrivilegesRequiredOverridesAllowed=dialog
[Files]
; 递归包含 windeployqt 产出的整个目录
Source: "release\*"; DestDir: "{app}"; Flags: ignoreversion recursesubdirs createallsubdirs
[Icons]
Name: "{group}\{#MyAppName}"; Filename: "{app}\{#MyAppExeName}"
Name: "{commondesktop}\{#MyAppName}"; Filename: "{app}\{#MyAppExeName}"; Tasks: desktopicon
[Tasks]
Name: "desktopicon"; Description: "创建桌面快捷方式"; GroupDescription: "附加任务"
[Run]
Filename: "{app}\{#MyAppExeName}"; Description: "立即运行"; Flags: nowait postinstall skipifsilent几个实用细节:
AppId必须是稳定的 GUID,升级安装靠它识别同一应用;每次改会导致装出两个副本。- 需要管理员权限(写 Program Files)时加
[Setup]里的PrivilegesRequired=admin;纯用户级安装可用{userpf}。 - 若要附带 VC++ 运行库:
[Files]加一行vc_redist.x64.exe,[Run]加Filename: "{tmp}\vc_redist.x64.exe"; Parameters: "/install /quiet /norestart"。 - 卸载时保留用户数据:不要把配置写到
{app}(会被卸载删掉),应写到{userappdata}\YourApp。
#Linux:linuxdeployqt 与 AppImage
Linux 发行版众多、glibc 版本不一,最省事的跨发行版方案是 AppImage——一个自挂载的单一可执行文件,双击即可运行。
# 1. linuxdeployqt(社区工具,从 GitHub releases 下载 AppImage 版)
chmod +x linuxdeployqt-x86_64.AppImage
# 2. 准备一个 AppDir 目录结构
mkdir -p AppDir/usr/bin AppDir/usr/share/applications AppDir/usr/share/icons/hicolor/256x256/apps
cp build/Dashboard AppDir/usr/bin/
cp dashboard.png AppDir/usr/share/icons/hicolor/256x256/apps/dashboard.png
cat > AppDir/usr/share/applications/dashboard.desktop <<'EOF'
[Desktop Entry]
Type=Application
Name=Dashboard
Exec=Dashboard
Icon=dashboard
Categories=Utility;
EOF
# 3. 部署依赖并生成 AppImage
./linuxdeployqt-x86_64.AppImage AppDir/usr/share/applications/dashboard.desktop \
-appimage -qmldir=../qml -extra-plugins=platformthemes,styles生成的 Dashboard-x86_64.AppImage 可直接分发。注意两点:
- glibc 兼容性:AppImage 应在较老的 LTS 系统(如 Ubuntu 20.04)上构建,才能在新系统上跑;反过来不行。官方推荐使用
ubuntu-20.04的 Docker 镜像做构建环境。 - 发行版原生包(
.deb/.rpm)更适合企业内推:用dpkg-buildpackage或cpack。CMake 内置 CPack 可以一行生成 deb:
# CMakeLists.txt 末尾
set(CPACK_PACKAGE_NAME "dashboard")
set(CPACK_PACKAGE_VERSION "1.2.0")
set(CPACK_DEBIAN_PACKAGE_MAINTAINER "me@example.com")
set(CPACK_DEBIAN_PACKAGE_DEPENDS "libqt6core6, libqt6gui6, libqt6widgets6, qml6-module-qtquick-controls")
include(CPack)deb 的思路是声明依赖、由 apt 安装 Qt 库,而不是自带所有 DLL。好处是体积小、符合发行版规范;坏处是用户机器上 Qt 版本必须匹配。
#macOS:macdeployqt 与 DMG
macOS 的应用是 .app bundle(本质是个带固定结构的目录)。Qt 自带 macdeployqt 负责把 Qt 框架拷进 bundle 并修正 install_name_t 链接路径:
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64"
cmake --build build --config Release
# 部署:会自动处理 framework、插件与 QML
~/Qt/6.6.0/macos/bin/macdeployqt build/Dashboard.app -qmldir=../qml -dmg
# 签名(分发前必须,否则用户会看到"无法验证开发者")
codesign --deep --force --options runtime --sign "Developer ID Application: Your Name (TEAMID)" Dashboard.app
# 公证(Notarization,macOS 10.15+ 必需)
ditto -c -k --keepParent Dashboard.app Dashboard.zip
xcrun notarytool submit Dashboard.zip --keychain-profile "AC_PASSWORD" --wait
xcrun stapler staple Dashboard.app-dmg 参数会直接生成可分发的 .dmg 磁盘镜像(背景图可自定义)。签名与公证是 macOS 发布的硬门槛:未签名的应用在 Gatekeeper 下会被拦截,用户需要右键"打开"才能运行,体验极差。你需要 Apple 开发者账号(99 美元/年)才能拿到 Developer ID 证书。
#Qt 静态编译简介
动态链接要带一堆 DLL,静态编译把 Qt 编进 exe,得到一个单文件程序。优点是部署极简、启动略快;缺点很硬:
- 许可证风险:LGPL 要求用户能替换 Qt 库,静态链接会破坏这一点。闭源静态链接 Qt 需要商业授权(见下节)。
- 构建复杂:需要自己编译 Qt 源码(
configure -static -static-runtime),耗时长,且插件需手动用Q_IMPORT_PLUGIN静态导入。 - 体积:一个小程序的 exe 通常 20–40MB,且失去库的独立升级能力。
结论:除非有强需求(如单文件绿色工具)且已解决授权,否则优先动态链接部署。
#版本、日志与崩溃上报
发布不是终点,线上问题定位才是真本事。三件套必须提前做好:
// 1. 版本号:QCoreApplication 统一设置,便于日志与上报携带
QCoreApplication::setApplicationName("Dashboard");
QCoreApplication::setApplicationVersion("1.2.0");
QCoreApplication::setOrganizationName("MyCompany");
// 2. 日志:安装消息处理器,把 qDebug/qWarning/qCritical 落盘
void myMessageOutput(QtMsgType type, const QMessageLogContext &ctx, const QString &msg)
{
static QFile f(QStandardPaths::writableLocation(QStandardPaths::AppDataLocation)
+ "/app.log");
if (!f.isOpen()) f.open(QIODevice::Append | QIODevice::Text);
QTextStream ts(&f);
ts << QDateTime::currentDateTime().toString("yyyy-MM-dd HH:mm:ss.zzz ")
<< "[" << qEnumToString(type) << "] " << msg << '\n';
}
qInstallMessageHandler(myMessageOutput); // main() 中尽早调用Release 版要保留符号表:编译时加 -g(或 MSVC 的 /Zi 生成 PDB),把 PDB/dSYM 归档保存,崩溃后才能把地址还原成函数名。
第三件是崩溃转储。Qt 自身没有崩溃捕获机制,一旦发生段错误,进程直接消失、什么都不留。工业界通用做法是接入 Google Breakpad / Crashpad,或直接用 Sentry 这类托管服务:在 main() 里创建一个 ExceptionHandler 对象,指定 dump 输出目录,崩溃时它会生成 minidump 文件,下次启动时上传即可。接入成本大约二十行代码,但它是你定位"某台客户机上偶发崩溃"的唯一手段——没有转储,这类问题永远只能靠猜。
需要提醒的是,dump 文件本身只是一堆地址,必须与构建时归档的符号文件(Windows 的 PDB、Linux 的分离符号、macOS 的 dSYM)配对才能还原出函数名与行号。因此每次发版都要把符号文件按版本号归档保存,别随手删掉构建目录。
更新机制:桌面应用常见做法是发一个简单的 version.json,程序启动时比对,提示下载新安装包:
{
"version": "1.3.0",
"url": "https://example.com/dl/Dashboard_Setup_1.3.0.exe",
"sha256": "a1b2c3...",
"notes": "修复告警列表刷新异常;新增导出 CSV",
"force": false
}校验 sha256 是必须的,否则 HTTPS 被劫持时用户会装到恶意包。
#开源许可合规
Qt 提供商业许可与开源许可(GPL v2/v3、LGPL v3)。用开源版做闭源商业软件的合规要点:
- LGPL v3 允许闭源,但必须满足:① 动态链接(不静态链接 Qt 库、不修改 Qt 源码);② 提供替换 Qt 库的途径(通常是提供
.o目标文件,或在安装包中说明如何替换 DLL);③ 附带 LGPL 协议文本与 Qt 源码获取方式说明。 - GPL 版 Qt 要求你的整个程序也以 GPL 开源,闭源产品不能用。
- 部分模块只在商业版提供(如 Qt Charts 的某些特性、Qt for MCU、Design Studio 的部分功能),选购前要核对模块清单。
- 第三方库要单独核对许可证(例如某些图表库是 GPL,会"传染")。
合规性一句话总结:动态链接 + 随包附 LGPL 文本 + 提供 Qt 库替换方式 + 声明用了 Qt(在"关于"界面里)。具体条款以 Qt 官方最新说明与法务意见为准。
#性能优化与线上问题排查清单
性能 checklist:
- QML:动画只改
x/y/scale/opacity/rotation,避免动画width/height;大列表开clip但别滥用;Image用asynchronous: true+ 限定sourceSize;善用Loader延迟加载非首屏页面。 - C++:大批量模型更新用
beginResetModel或批量dataChanged(指定角色范围);避免每行数据都emit dataChanged。 - IO:文件与网络读写不放在主线程;日志批量 flush 而不是每条都写盘。
- 发布:确保是 Release 构建(
-DCMAKE_BUILD_TYPE=Release),Debug 版慢 3–10 倍且依赖调试库。
线上问题排查清单:
| 现象 | 排查方向 |
|---|---|
| 双击无反应 | 平台插件缺失(platforms/qwindows.dll);或 exe 位数与系统不符 |
| 报 "no Qt platform plugin" | 插件目录名/位置错误;或 QT_PLUGIN_PATH 被污染 |
启动时报缺 xxx.dll | windeployqt 参数漏了 --qmldir;或 VC++ 运行库未装 |
| 界面文字全方框 | 字体未打包或平台主题插件缺失 |
| QML 报 "module not found" | QML 模块未部署;检查 qml/ 目录是否随包 |
| 高分屏模糊 | Windows 设置 Qt::AA_EnableHighDpiScaling(Qt 6 默认开启);提供 2x 图标 |
| 部分机器崩溃 | 显卡驱动/OpenGL 版本问题,改用 QT_QUICK_BACKEND=software 验证 |
| 中文乱码 | 源文件未存 UTF-8;或 QStringConverter 编码选错(见 p5-04) |
| 程序卡死无响应 | 主线程做了阻塞 IO 或死循环;用调试器看主线程栈 |
排查黄金法则:先在干净虚拟机上复现,再用 Dependencies/ldd/otool 查依赖,最后看日志与崩溃转储。
#小结
- 发布 = 收集依赖 → 裁剪 → 制作安装包 → 在干净机器验证;跳过验证必然出事。
- Windows 用
windeployqt --qmldir,MSVC 需附带 VC++ 运行库;平台插件platforms/qwindows.dll缺失是最常见故障。 - Linux 首选 AppImage(在老 LTS 上构建),企业内推可用 CPack 生成 deb 并声明依赖。
- macOS 必须
macdeployqt -dmg+codesign+ 公证,否则被 Gatekeeper 拦截。 - 静态编译虽部署简单,但与 LGPL 冲突且构建复杂,默认不选。
- 上线前做好版本号、日志落盘、符号表归档、崩溃转储与带 SHA256 校验的更新机制。
#练习
- 把 p5-04 的编辑器用 Release 构建后执行
windeployqt,统计部署目录大小,再尝试用--no-translations等参数裁剪,记录每一项能省多少。 - 写一个 Inno Setup 脚本,要求:写入开始菜单与桌面快捷方式、卸载时保留
QSettings用户配置、安装结束时可选择立即运行。 - 在虚拟机(或 Docker 的 ubuntu:20.04)中安装一个纯净系统,把你的程序拷过去运行,记录所有报错并逐个修复,直到双击即可正常启动。
- 给你的程序接入
qInstallMessageHandler日志落盘,并模拟一次空指针崩溃,验证日志与崩溃转储中能看到有意义的调用栈。