Qt Installer教程：轻松构建跨平台应用 – wiki词典

Qt Installer教程：轻松构建跨平台应用

在软件开发领域，跨平台部署一直是一个挑战。Qt 框架以其强大的跨平台能力而闻名，而 Qt Installer Framework 则进一步简化了这一过程，允许开发者为 Linux、Microsoft Windows 和 macOS 创建定制化的、具有原生观感的安装包。本教程将详细介绍如何使用 Qt Installer Framework 轻松构建您的跨平台应用程序安装程序。

1. 为什么选择 Qt Installer Framework？

Qt Installer Framework 是一个强大的工具集，它不仅仅是一个简单的打包工具。它提供了一整套解决方案，让您可以：

• 创建定制化安装程序： 根据您的品牌形象和应用程序需求，完全控制安装向导的流程和界面。
• 支持多平台： 一次开发，多平台部署，为 Linux、Windows 和 macOS 用户提供一致的安装体验。
• 灵活的组件管理： 支持将应用程序拆分为多个可选择安装的组件，例如核心程序、文档、示例等。
• 在线安装与更新： 可以创建在线安装程序，动态从服务器下载组件，并支持方便的应用程序更新。
• 脚本化控制： 通过 QML 脚本实现复杂的安装逻辑，例如创建快捷方式、修改注册表、执行自定义命令等。

2. 准备工作 (Prerequisites)

在开始之前，请确保您的开发环境中已安装以下组件：

• Qt Installer Framework： 您可以通过 Qt Maintenance Tool 安装它（在 “Developer and Design Tools” 下选择 “Qt Installer Framework 3.x”），或者从 Qt 官网单独下载。
• 一个已编译的 Qt 应用程序： 这是您希望打包到安装程序中的目标应用程序。
• 部署工具：
  • Windows: windeployqt.exe (通常位于您的 Qt 安装目录的 bin 文件夹内)。
  • macOS: macdeployqt (通常位于您的 Qt 安装目录的 bin 文件夹内)。
  • Linux: 对于 Linux，部署通常涉及手动复制共享库或使用第三方工具如 linuxdeployqt (非官方 Qt 工具，但被广泛使用)。

3. 核心概念

理解 Qt Installer Framework 的核心组件是成功构建安装程序的关键：

• binarycreator： 这是生成安装程序可执行文件的主要命令行工具。它将您的配置和包文件编译成最终的安装程序。
• config.xml： 这个 XML 文件定义了安装程序的全局配置，包括安装程序的名称、版本、发布者、默认安装目录以及安装向导的视觉样式等。
• packages 目录： 这是一个包含一个或多个子目录的文件夹，每个子目录代表一个可安装的应用程序组件（包）。
• package.xml： 位于每个组件的 meta 目录中，这个 XML 文件描述了该组件的属性，例如显示名称、描述、版本、发布日期以及可能存在的依赖关系。
• data 目录： 同样位于每个组件的目录中，这个文件夹包含了您应用程序的实际文件，这些文件将在安装过程中被复制到用户的系统。
• meta 目录： 位于每个组件的目录中，这个文件夹包含 package.xml，还可以包含用于自定义安装逻辑的 QML 脚本文件 (installscript.qs)。

4. 分步教程：构建您的第一个安装程序

让我们以一个简单的 Qt 应用程序为例，一步步创建其跨平台安装程序。

步骤 1: 准备您的应用程序进行部署

首先，您需要收集应用程序所需的所有 Qt 库和插件。

对于 Windows：

1. 在发布模式下编译您的 Qt 应用程序。
2. 打开命令提示符，导航到应用程序的构建目录（.exe 文件所在的位置）。
3. 运行 windeployqt.exe，后跟您的应用程序可执行文件的名称。
   bash
C:\Qt\5.15.2\msvc2019_64\bin\windeployqt.exe your_application.exe
   这将把所有必需的 DLL、插件和其他依赖项复制到您的可执行文件旁边。

对于 macOS：

1. 在发布模式下编译您的 Qt 应用程序。
2. 打开终端，导航到应用程序的构建目录。
3. 对您的应用程序 bundle 运行 macdeployqt。
   bash
/Users/user/Qt/5.15.2/clang_64/bin/macdeployqt your_application.app
   这将把所有必需的 Qt 框架和插件捆绑到您的 .app bundle 中。

对于 Linux：

Linux 上的部署通常需要确保目标系统安装了必要的 Qt 库，或者静态链接 Qt。对于可部署的包，您可能需要手动复制共享库，或者使用 linuxdeployqt 等工具。在本教程中，我们假设您已经将应用程序的可执行文件及其所需的共享库收集到一个目录中。

步骤 2: 设置安装程序项目结构

创建一个新的目录作为您的安装程序项目。在此目录中，创建两个子目录：config 和 packages。

your_installer_project/
├── config/
└── packages/

步骤 3: 创建 config.xml

在 config 目录中，创建一个名为 config.xml 的文件，内容如下。此文件定义了安装程序的全局属性。

“`xml

您的应用程序名称
1.0.0

您的公司名称
您的应用程序名称
@ApplicationsDir@/您的应用程序名称
Modern
800
600

“`

• <Name>: 您的应用程序的名称。
• <Version>: 您的应用程序的版本。
• <Title>: 安装程序窗口中显示的标题。
• <Publisher>: 您的公司或组织名称。
• <StartMenuDir>: 启动菜单条目（Windows）或应用程序文件夹（macOS/Linux）的默认名称。
• <TargetDir>: 默认安装目录。@ApplicationsDir@ 是一个预定义变量，它解析为每个操作系统上的标准应用程序目录。
• <WizardStyle>: 定义安装程序的视觉样式。
• <WizardDefaultWidth> / <WizardDefaultHeight>: 设置安装程序窗口的默认尺寸。

步骤 4: 创建一个应用程序包

现在，为您的应用程序定义一个可安装组件（包）。

1. 创建组件目录： 在 packages 目录中，为您的组件创建一个子目录。常见的命名约定是 com.vendor.product。
   your_installer_project/
├── config/
└── packages/
└── com.yourcompany.yourapp/
2. 创建 meta 和 data 目录： 在 com.yourcompany.yourapp 中，创建 meta 和 data 子目录。
   your_installer_project/
├── config/
└── packages/
└── com.yourcompany.yourapp/
├── meta/
└── data/

3. 创建 package.xml： 在 meta 目录中，创建 package.xml 来描述此组件。

   xml
<?xml version="1.0" encoding="UTF-8"?>
<Package>
<DisplayName>您的应用程序核心</DisplayName>
<Description>安装核心应用程序文件。</Description>
<Version>1.0.0</Version>
<ReleaseDate>2025-12-23</ReleaseDate>
<DefaultInstallRoutable>true</DefaultInstallRoutable>
<Script>installscript.qs</Script>
</Package>

   • <DisplayName>: 在安装程序组件选择页面中显示的名称。
   • <Description>: 组件的简短描述。
   • <Version>: 此特定包的版本。
   • <ReleaseDate>: 包的发布日期。
   • <DefaultInstallRoutable>: 如果为 true，此组件默认选中安装。
   • <Script>: (可选) 指定一个 QML 脚本，用于自定义安装逻辑。我们将在下一步创建一个简单的脚本。

4. 创建 installscript.qs (可选)： 在 meta 目录中，创建 installscript.qs。此脚本可以在安装过程中执行操作，例如创建快捷方式。

   “`javascript
   function Component()
   {
   // 默认构造函数
   }

   Component.prototype.createOperations = function()
   {
   // 调用基类的 createOperations 函数
   component.createOperations();

   if (systemInfo.productType === "windows") {
       // 在桌面上创建快捷方式
       component.addOperation("CreateShortcut", "@TargetDir@/your_application.exe", "@DesktopDir@/您的应用程序名称.lnk");
       // 在开始菜单中创建快捷方式
       component.addOperation("CreateShortcut", "@TargetDir@/your_application.exe", "@StartMenuDir@/您的应用程序名称.lnk");
   } else if (systemInfo.productType === "mac") {
       // 在 macOS 上，.app bundle 通常被拖到 Applications 文件夹，因此不需要显式快捷方式。
       // 如果需要，您可以添加特定于 macOS 的操作。
   } else if (systemInfo.productType === "linux") {
       // 对于 Linux，您可以创建 .desktop 文件或类似的文件。
       // 这是一个简化示例。
       component.addOperation("CreateShortcut", "@TargetDir@/your_application", "@HomeDir@/.local/share/applications/your_application.desktop");
       component.addOperation("Execute", "chmod", "+x", "@TargetDir@/your_application");
   }
   

   }
   “`

   • 此脚本使用 systemInfo.productType 检测操作系统并创建平台特定的快捷方式。
   • @TargetDir@、@DesktopDir@、@StartMenuDir@、@HomeDir@ 都是预定义变量。

5. 复制应用程序文件： 将您的已部署应用程序文件（可执行文件、DLL、插件等，来自步骤 1）复制到组件的 data 目录中。

   your_installer_project/
├── config/
└── packages/
└── com.yourcompany.yourapp/
├── meta/
│ ├── package.xml
│ └── installscript.qs
└── data/
├── your_application.exe (或 your_application.app, 或 your_application)
├── Qt5Core.dll
├── platforms/
│ └── qwindows.dll
└── ... (其他依赖项)
   请确保 installscript.qs 中的可执行文件名称与 data 目录中的实际可执行文件名称匹配。

步骤 5: 生成安装程序

现在，使用 binarycreator 工具生成您的安装程序。

1. 打开命令提示符或终端。
2. 导航到您的 your_installer_project 目录。
3. 找到 binarycreator 可执行文件。它通常位于 Qt Installer Framework 安装目录的 bin 文件夹中（例如，Windows 上是 C:\Qt\Tools\QtInstallerFramework\3.x\bin\binarycreator.exe）。

4. 运行 binarycreator 命令：

   对于 Windows：
   bash
"C:\Qt\Tools\QtInstallerFramework\3.x\bin\binarycreator.exe" -c config\config.xml -p packages YourApplicationInstaller.exe

   对于 Linux/macOS：
   bash
/path/to/Qt/Tools/QtInstallerFramework/3.x/bin/binarycreator -c config/config.xml -p packages YourApplicationInstaller

   • -c config/config.xml：指定配置文件的路径。
   • -p packages：指定 packages 目录的路径。
   • YourApplicationInstaller.exe (或 YourApplicationInstaller)：输出安装程序可执行文件的名称。

   如果成功，将在 your_installer_project 目录中创建一个安装程序可执行文件（例如，Windows 上的 YourApplicationInstaller.exe）。

步骤 6: 测试安装程序

运行生成的安装程序可执行文件。您应该会看到标准的安装向导页面，包括：

• 介绍页面。
• 许可协议页面（如果您在 config.xml 中添加了许可文件）。
• 选择组件页面（显示“您的应用程序核心”）。
• 选择安装目录页面。
• 安装进度页面。
• 完成页面。

安装完成后，检查您的应用程序是否已安装到指定目录，以及快捷方式是否正确创建。

5. 高级主题

• 自定义页面： 您可以使用 QML 向安装程序添加自定义向导页面，以从用户那里收集额外信息或提供更多选项。
• 在线安装程序： 框架支持创建在线安装程序，这些安装程序在安装过程中从远程存储库下载组件。这需要使用 repogen 工具。
• 本地化： 您可以通过提供不同语言的翻译文件来本地化您的安装程序。
• 多个组件： 您可以在 packages 目录中定义多个包，允许用户选择安装应用程序的哪些部分（例如，核心应用程序、文档、示例）。
• 更新和卸载： 生成的安装程序还处理现有安装的更新和应用程序的卸载。

6. 总结

Qt Installer Framework 提供了一种高效、灵活的方式来为您的 Qt 应用程序构建专业的跨平台安装程序。通过理解其核心概念并遵循本教程中的步骤，您可以为您的用户提供无缝且一致的安装体验，从而专注于应用程序本身的开发。