QSimpleUpdater 详解详细使用教程为 Qt 应用一键接入自动更新功能一、QSimpleUpdater 介绍1、QSimpleUpdater 是什么2、核心概念与工作流程3、集成与使用 (C 示例)3.1、配置与检查3.2、处理信号 - 弹出更新对话框示例4、高级配置 (JSON 格式)5、重要注意事项6、 替代方案二、完整使用教程1、下载并解压源码2、将QSimpleUpdater 源码添加到工程3、新建一个更新程序及相关文件3、将需要更新的文件上传到服务器4、修改源码实现更新三、源码分享1、工程结构2、qsimpleUpdater.pro3、mainWindow.ui3、mainWindow.cpp4、更新效果展示5、完整工程下载一、QSimpleUpdater 介绍1、QSimpleUpdater 是什么QSimpleUpdater是一个为Qt 应用程序设计的、轻量级且易于集成的自动更新框架。它的核心目标是简化在 Qt (C) 或 Qt Quick (QML) 应用中实现自动检查更新、下载新版本和安装流程的过程。主要特点轻量级代码简洁不引入过多依赖或复杂性。跨平台支持 Windows、macOS、Linux 等主要桌面平台。灵活允许开发者完全自定义更新过程中的用户界面 (UI) 和用户体验 (UX)。无外部依赖主要使用 Qt 自身的网络 (QNetworkAccessManager) 和文件处理能力。模块化核心的更新逻辑与 UI 展示分离方便定制。2、核心概念与工作流程一个典型的 QSimpleUpdater 工作流程如下配置在你的应用程序启动时配置QSimpleUpdater实例。关键配置包括更新检查 URL一个指向特定文件的 URL通常是 JSON 或 TXT该文件包含最新的版本信息如版本号、下载链接、变更日志等。应用名称/组件标识符用于区分同一应用的不同可更新组件可选。其他设置如是否启用、检查频率、是否显示通知等。检查更新调用QSimpleUpdater的checkForUpdates()方法。它会异步地向配置的 URL 发送 HTTP GET 请求。解析响应QSimpleUpdater获取并解析远程文件的内容。它期望找到一个有效的版本号字符串如2.3.0或者一个结构化的 JSON 对象包含更多信息。比较版本将远程获取的最新版本号与应用程序的当前版本号需要在代码中设置进行比较。通知结果根据比较结果QSimpleUpdater会发出信号updateAvailable(QString, QString)当发现新版本时发出参数通常包含新版本号和下载 URL (如果配置文件中提供了)。upToDate()当当前版本是最新时发出。checkError(QString)当检查过程出错如网络问题、解析错误时发出。处理更新在收到updateAvailable信号后你的应用程序代码需要响应通知用户弹出一个对话框、系统托盘通知等告知用户有新版本可用并提供更新选项立即更新、稍后提醒、忽略此版本等。下载更新包如果用户选择更新使用QSimpleUpdater的downloadUpdate(const QUrl)方法开始下载新版本的安装包如 .exe, .dmg, .appimage, .deb 等。QSimpleUpdater会发出downloadFinished(const QUrl, const QString)信号报告下载成功及文件保存路径或downloadError(const QUrl, const QString)报告失败。执行安装收到downloadFinished信号后你的代码需要启动下载好的安装程序。这通常使用QProcess来执行外部安装程序。注意QSimpleUpdater本身不包含安装逻辑安装过程由外部安装程序处理。你的应用程序通常需要在启动安装程序后退出。3、集成与使用 (C 示例)3.1、配置与检查#includeQSimpleUpdater.h// ... 在你的主窗口或应用初始化代码中 ...// 创建或获取 QSimpleUpdater 实例 (通常作为成员变量)QSimpleUpdater*updaterQSimpleUpdater::getInstance();// 配置更新源。假设我们有一个 TXT 文件只包含版本号 2.3.0updater-setModuleName(MyAwesomeApp);// 设置模块标识符updater-setModuleVersion(1.0.0);// 设置当前应用版本updater-setCheckUrl(https://your-update-server.com/version.txt);// 设置检查URLupdater-setDownloadUrl(https://your-update-server.com/downloads/MyApp_2.3.0_Installer.exe);// 可选预置下载URL。也可在JSON中提供。// 连接信号槽connect(updater,QSimpleUpdater::updateAvailable,this,MainWindow::onUpdateAvailable);connect(updater,QSimpleUpdater::upToDate,this,MainWindow::onUpToDate);connect(updater,QSimpleUpdater::checkError,this,MainWindow::onCheckError);// 开始检查更新updater-checkForUpdates();3.2、处理信号 - 弹出更新对话框示例voidMainWindow::onUpdateAvailable(constQStringversion,constQString/* module */){// 假设 downloadUrl 要么在配置时 setDownloadUrl 设置了要么在解析的 JSON 中提供了并保存在 updater 内部QString downloadUrlupdater-getDownloadUrl();QMessageBoxmsgBox(this);msgBox.setIcon(QMessageBox::Information);msgBox.setWindowTitle(tr(Update Available));msgBox.setText(tr(A new version (%1) of MyAwesomeApp is available!).arg(version));msgBox.setInformativeText(tr(Do you want to download and install it now?));msgBox.setStandardButtons(QMessageBox::Yes|QMessageBox::No);msgBox.setDefaultButton(QMessageBox::Yes);if(msgBox.exec()QMessageBox::Yes){// 用户选择更新开始下载updater-downloadUpdate(QUrl(downloadUrl));// 连接 downloadFinished/downloadError 信号处理后续}}voidMainWindow::onDownloadFinished(constQUrlurl,constQStringfilePath){// 下载完成filePath 是下载好的安装包路径QProcess installer;installer.setProgram(filePath);// 设置要执行的安装程序路径// 启动安装程序 (可能需要特定参数)if(installer.startDetached()){// 启动成功可以退出当前应用qApp-quit();}else{// 启动失败提示用户手动安装QMessageBox::critical(this,tr(Installation Failed),tr(Failed to launch the installer. Please manually run the downloaded file: %1).arg(filePath));}}4、高级配置 (JSON 格式)QSimpleUpdater 支持解析 JSON 文件以提供更丰富的信息。一个典型的 JSON 配置文件可能如下{version:2.3.0,download-url:https://your-update-server.com/downloads/MyApp_2.3.0_Installer.exe,changelog:https://your-update-server.com/changelog/2.3.0.html,mandatory:false,checksum:md5:5d41402abc4b2a76b9719d911017c592// 可选用于验证下载文件完整性}在代码中你需要告诉 QSimpleUpdater 使用 JSON 解析器updater-setCustomValueParser([](constQByteArraydata)-QString{QJsonDocument docQJsonDocument::fromJson(data);if(doc.isObject()){QJsonObject objdoc.object();returnobj.value(version).toString();// 返回版本字符串}returnQString();// 解析失败返回空});5、重要注意事项UI 完全自定义QSimpleUpdater 只负责核心的检查、比较和下载逻辑。如何通知用户更新、展示更新内容变更日志、下载进度、安装确认等完全由开发者使用 Qt 的 UI 组件如 QDialog, QProgressDialog, QSystemTrayIcon或 QML 来实现。版本号格式QSimpleUpdater 使用简单的字符串比较 (QString::compare)。确保你的版本号字符串遵循一个一致的、可比较的格式如主版本号.次版本号.修订号。对于更复杂的版本号带字母后缀可能需要自定义比较逻辑。安全性自动更新涉及下载和执行外部文件存在安全风险使用 HTTPS确保检查 URL 和下载 URL 使用https://。文件校验如果提供checksum字段在下载完成后验证文件哈希值MD5, SHA1, SHA256后再执行安装。代码签名发布的安装程序应进行代码签名如 Windows 的 Authenticode, macOS 的 Developer ID并在客户端验证签名这通常需要额外代码QSimpleUpdater 不直接处理。安装程序QSimpleUpdater 不包含创建安装包的功能。你需要使用其他工具如 Inno Setup, NSIS, WiX Toolset on Windows; macOS .pkg or .dmg; Linux .deb, .rpm, AppImage来生成安装程序。静默更新/后台更新实现完全无用户交互的更新如某些服务类应用需要更复杂的逻辑可能涉及服务/守护进程QSimpleUpdater 的核心功能不直接支持此场景。6、 替代方案Qt Online Installer FrameworkQt 官方提供的强大框架功能丰富包括安装、更新、组件管理、仓库管理但更复杂且主要用于安装 Qt 本身或大型套件。Sparkle (macOS)macOS 上非常流行的更新框架有 Qt 封装 (qsparkle)。WinSparkle (Windows)Windows 上的 Sparkle 移植。Omaha/Google Update (Windows)Google 使用的复杂更新系统。其他第三方库libappupdate, AutoUpdater 等。选择 QSimpleUpdater 的场景当你需要一个简单、轻量、易于集成到现有 Qt 桌面应用、且允许完全自定义 UI 的自动更新解决方案时。二、完整使用教程1、下载并解压源码从github下载源码git clone https://github.com/alex-spataru/QSimpleUpdater.git解压到当前文件夹2、将QSimpleUpdater 源码添加到工程新建一个QWidget工程选择编译器在新建工程路径下面新建3rd-party文件夹将解压的源码重命名为QSimpleUpdater并拷贝到3rd-party文件夹下全部拷贝将QSimpleUpdater添加到工程中打开.pro文件添加下面一段话include(3rd-party/QSimpleUpdater/QSimpleUpdater.pri)编译一下就会出现QSimpleUpdater源码3、新建一个更新程序及相关文件在当前程序中随便制作一个程序将程序放到阿里云服务器上修改mainwindow.ui文件如下编译生成一个.exe文件编译完成后会在工程目录\build\Desktop_Qt_6_9_0_MinGW_64_bit-Debug\debug下会有一个.exe文件新建一个json文件比如ota.json并填入如下内容{updates:{windows:{open-url:,latest-version:3.0,download-url:https://espidftest.oss-xxxxxxxxx,changelog:This is an example changelog for Windows. Go on...,mandatory:true},osx:{open-url:,latest-version:1.0,download-url:https://raw.githubusercontent.com/alex-spataru/QSimpleUpdater/master/tutorial/download/YesItWorks.jpg,changelog:This is an example changelog for Mac OS X. Go on...,mandatory:true},linux:{open-url:,latest-version:1.0,download-url:https://raw.githubusercontent.com/alex-spataru/QSimpleUpdater/master/tutorial/download/YesItWorks.jpg,changelog:This is an example changelog for Linux. Go on...,mandatory:true},ios:{open-url:,latest-version:1.0,download-url:https://raw.githubusercontent.com/alex-spataru/QSimpleUpdater/master/tutorial/download/YesItWorks.jpg,changelog:This is an example changelog for iOS. Go on...,mandatory:true},android:{open-url:,latest-version:1.0,download-url:https://raw.githubusercontent.com/alex-spataru/QSimpleUpdater/master/tutorial/download/YesItWorks.jpg,changelog:This is an example changelog for Android. Go on...,mandatory:true}}}下载路径稍后会更改download-url: https://espidftest.oss-xxxxxxxxx,。3、将需要更新的文件上传到服务器我们使用阿里云OSS服务器打开官网https://oss.console.aliyun.com/overview新建一个账号新建一个Bucket填入名称点击确定修改权限读写权限改为公共读写上传上一步生成的.exe更新程序文件等待上传完成复制上传文件下载链接进入ota.json文件复制URL进入ota.json文件并修改latest-version将ota.json文件以同样的方式上传到阿里云服务器4、修改源码实现更新工程结构如下图所示修改mainwindow.ui文件如下删除新程序提升mainWindow.cpp代码如下#includemainwindow.h#includeui_mainwindow.h#includeQSimpleUpdater.hMainWindow::MainWindow(QWidget*parent):QMainWindow(parent),ui(newUi::MainWindow){ui-setupUi(this);}MainWindow::~MainWindow(){deleteui;}voidMainWindow::on_btnUpdate_clicked(){QString urlhttps://espidftest.oss-xxxxxxxxxx;auto*updaterQSimpleUpdater::getInstance();// 当检测到更新时显示通知默认trueupdater-setNotifyOnUpdate(url,true);// 当更新完成后显示通知updater-setNotifyOnFinish(url,true);updater-setDownloadDir(url,QCoreApplication::applicationDirPath()/updata);updater-setUseCustomInstallProcedures(url,true);// 启用内置下载器默认trueupdater-setDownloaderEnabled(url,true);updater-setModuleVersion(url,1.0);autoversionupdater-getLatestVersion(url);autonoteupdater-getChangelog(url);this-ui-label-setText(laste version:version\note:note);// 3. 连接信号下载完成后执行绿色覆盖更新connect(updater,QSimpleUpdater::downloadFinished,this,MainWindow::onUpdateDownloaded);// 开始检查更新updater-checkForUpdates(url);}voidMainWindow::onUpdateDownloaded(){// 1. 路径QString appDirQCoreApplication::applicationDirPath();QString newFileappDir/updata/QSU_Update.bin;// 新文件路径QString targetappDir/qsimpleUpdater.exe;// 目标程序// 2. 写更新脚本QString batContentR( echo off :loop taskkill /f /im qsimpleUpdater.exe 2nul timeout /t 1 /nobreak nul :: 强制删除旧文件 del /f /q qsimpleUpdater.exe :: 复制新文件 copy /b /y updata\QSU_Update.bin qsimpleUpdater.exe :: 启动新程序 start qsimpleUpdater.exe :: 删除自身 del %~f0 exit );// 3. 保存脚本QFilebat(appDir/update.bat);bat.open(QIODevice::WriteOnly|QIODevice::Text);bat.write(batContent.toUtf8());bat.close();// 关键必须这个顺序 // 先启动脚本QProcess::startDetached(appDir/update.bat);// 程序立刻退出QCoreApplication::quit();}将你服务器的ota.json文件下载路径复制到QString url https://espidftest.oss;三、源码分享1、工程结构2、qsimpleUpdater.proQTwidgets CONFIGc17#You can make your code fail to compileifit uses deprecated APIs.#In order todoso,uncomment the following line.#DEFINESQT_DISABLE_DEPRECATED_BEFORE0x060000# disables all the APIs deprecated before Qt6.0.0SOURCES\ main.cpp \ mainwindow.cpp HEADERS\ mainwindow.h FORMS\ mainwindow.ui#Default rulesfordeployment.qnx:target.path/tmp/$${TARGET}/binelse:unix:!android:target.path/opt/$${TARGET}/bin!isEmpty(target.path):INSTALLStargetinclude(3rd-party/QSimpleUpdater/QSimpleUpdater.pri)3、mainWindow.ui3、mainWindow.cpp#includemainwindow.h#includeui_mainwindow.h#includeQSimpleUpdater.hMainWindow::MainWindow(QWidget*parent):QMainWindow(parent),ui(newUi::MainWindow){ui-setupUi(this);}MainWindow::~MainWindow(){deleteui;}voidMainWindow::on_btnUpdate_clicked(){QString urlhttps://espidftest.oss-xxxxxxxxx;auto*updaterQSimpleUpdater::getInstance();// 当检测到更新时显示通知默认trueupdater-setNotifyOnUpdate(url,true);// 当更新完成后显示通知updater-setNotifyOnFinish(url,true);updater-setDownloadDir(url,QCoreApplication::applicationDirPath()/updata);updater-setUseCustomInstallProcedures(url,true);// 启用内置下载器默认trueupdater-setDownloaderEnabled(url,true);updater-setModuleVersion(url,1.0);autoversionupdater-getLatestVersion(url);autonoteupdater-getChangelog(url);this-ui-label-setText(laste version:version\note:note);// 3. 连接信号下载完成后执行绿色覆盖更新connect(updater,QSimpleUpdater::downloadFinished,this,MainWindow::onUpdateDownloaded);// 开始检查更新updater-checkForUpdates(url);}voidMainWindow::onUpdateDownloaded(){// 1. 路径QString appDirQCoreApplication::applicationDirPath();QString newFileappDir/updata/QSU_Update.bin;// 新文件路径QString targetappDir/qsimpleUpdater.exe;// 目标程序// 2. 写更新脚本QString batContentR( echo off :loop taskkill /f /im qsimpleUpdater.exe 2nul timeout /t 1 /nobreak nul :: 强制删除旧文件 del /f /q qsimpleUpdater.exe :: 复制新文件 copy /b /y updata\QSU_Update.bin qsimpleUpdater.exe :: 启动新程序 start qsimpleUpdater.exe :: 删除自身 del %~f0 exit );// 3. 保存脚本QFilebat(appDir/update.bat);bat.open(QIODevice::WriteOnly|QIODevice::Text);bat.write(batContent.toUtf8());bat.close();// 关键必须这个顺序 // 先启动脚本QProcess::startDetached(appDir/update.bat);// 程序立刻退出QCoreApplication::quit();}4、更新效果展示5、完整工程下载博客首页下载完整工程