部署插件

本主题解释了如何在运行时部署 Qt 或您的应用程序的插件库。如果您使用静态插件，则插件代码已经包含在您的应用程序可执行文件中，无需单独的部署步骤。

插件目录

在 Qt 中，当应用程序启动时，应用程序的可执行文件目录是 Qt 搜索插件的基本目录。

例如，在 Windows 上，如果应用程序位于 C:\Program Files\MyApp，并且它具有一个样式插件，Qt 会查找 C:\Program Files\MyApp\styles。

有关查找您的应用程序的可执行文件位置的信息，请参阅 QCoreApplication::applicationDirPath().

Qt 还会在 QLibraryInfo::path(QLibraryInfo::PluginsPath) 指定的目录中查找，该目录通常位于 QTDIR/plugins；QTDIR 是 Qt 安装目录。如果要让 Qt 在其他位置查找，您可以使用 QCoreApplication::addLibraryPath() 调用添加所需数量的路径。如果您想设置自己的路径（多个），可以使用 QCoreApplication::setLibraryPaths().

或者，您可以使用 qt.conf 文件来覆盖编译到 Qt 库中的硬编码路径。有关更多信息，请参阅使用 qt.conf。

另一种可能性是在运行应用程序之前设置 QT_PLUGIN_PATH 环境变量；多个路径可以用系统路径分隔符分隔。设置后，Qt 将在由此变量指定的路径中查找插件。

注意：不要将 QT_PLUGIN_PATH 作为系统范围的环境变量导出，因为它可能会干扰其他 Qt 安装。

在加载插件时，Qt 库会进行一些完整性检查，以确定是否可以加载和使用插件。此完整性检查使您可以同时安装多个 Qt 版本和配置。

以下规则适用

与较高级别次版本号的 Qt 库链接的插件不能由较低次版本号的库加载。

示例： Qt 6.2.0 将不会加载使用 Qt 6.3.0 编译的插件。 示例： Qt 6.2.0 将加载使用 Qt 6.1.0 编译的插件。 示例： Qt 6.2.0 将加载使用 Qt 6.2.1 编译的插件。
与较高级别主版本号的 Qt 库链接的插件不能由较低主版本号的库加载。

示例： Qt 6.0.0 将不会加载使用 Qt 5.15.0 编译的插件。

在构建用于扩展应用的插件时，确保插件的配置与应用程序相同非常重要。这意味着如果应用程序以发布模式构建，则插件也应以发布模式构建。对于Unix操作系统，插件系统将不会加载与应用程序构建模式不同的插件。

一些问题可能导致正确编写的插件无法与设计用来使用它们的程序一起工作。其中许多问题与插件和应用程序的构建方式不同有关，这通常是由于单独的构建系统和流程引起的。

要从Qt获取有关它试图加载的每个插件的诊断信息，请使用QT_DEBUG_PLUGINS环境变量。在启动应用程序的环境中设置此变量为一个非零值。

以下表格描述了开发人员在创建插件时遇到的常见问题及其可能的解决方案。

问题	原因	解决方案
插件即使在应用程序直接打开时也会静默失败加载。Qt Designer在其帮助\|关于插件对话框中显示插件库，但每个下面都没有列出插件。	应用程序及其插件以不同的模式构建。	以可执行文件的相同配置构建插件。