本页内容

androiddeployqt 工具

构建 Android 软件包涉及许多步骤,因此 Qt 提供了一个工具来为您处理这些工作。Android Deploy Qt 工具处理的步骤在《在 Android 上部署应用程序》一节中进行了说明。

运行 androiddeployqt 之前的先决条件

在手动运行该工具之前,您需要通过CMake 或qmake 配置项目,以生成Makefiles 文件以及一个JSON 文件(例如android-<target_name>-deployment-settings.json ),其中包含androiddeployqt 所使用的关键设置。

注意: 不建议修改 androiddeployqt 的 JSON 文件。

为 androiddeployqt 准备环境时,请将项目配置在与源代码目录不同的目录中。有关项目配置的更多信息,请参阅《从命令行构建 Qt for Android 项目》。

命令行参数

运行该工具时,唯一的必填命令行参数是--input 和--output 。其他命令行参数虽为可选,但非常有用。通过向 androiddeployqt 传递--help 参数,可查看以下参数列表。

Syntax: androiddeployqt --output <destination> [options]

Creates an Android package in the build directory <destination> and
builds it into an .apk file.

Optional arguments:
    --input <inputfile>: Reads <inputfile> for options generated by
       qmake. A default file name based on the current working
       directory will be used if nothing else is specified.

    --deployment <mechanism>: Supported deployment mechanisms:
       bundled (default): Includes Qt files in stand-alone package.
       unbundled: Assumes native libraries are present on the device
       and does not include them in the APK.

    --aab: Build an Android App Bundle.

    --no-build: Do not build the package, it is useful to just install
       a package previously built.

    --install: Installs apk to device/emulator. By default this step is
       not taken. If the application has previously been installed on
       the device, it will be uninstalled first.

    --reinstall: Installs apk to device/emulator. By default this step
       is not taken. If the application has previously been installed on
       the device, it will be overwritten, but its data will be left
       intact.

    --device [device ID]: Use specified device for deployment. Default
       is the device selected by default by adb.

    --android-platform <platform>: Builds against the given android
       platform. By default, the highest available version will be
       used.

    --release: Builds a package ready for release. By default, the
       package will be signed with a debug key.

    --sign <url/to/keystore> <alias>: Signs the package with the
       specified keystore, alias and store password.
       Optional arguments for use with signing:
         --storepass <password>: Keystore password.
         --storetype <type>: Keystore type.
         --keypass <password>: Password for private key (if different
           from keystore password.)
         --sigfile <file>: Name of .SF/.DSA file.
         --digestalg <name>: Name of digest algorithm. Default is
           "SHA-256".
         --sigalg <name>: Name of signature algorithm. Default is
           "SHA256withRSA".
         --tsa <url>: Location of the Time Stamping Authority.
         --tsacert <alias>: Public key certificate for TSA.
         --internalsf: Include the .SF file inside the signature block.
         --sectionsonly: Do not compute hash of entire manifest.
         --protected: Keystore has protected authentication path.
         --jarsigner: Deprecated, ignored.

       NOTE: To conceal the keystore information, the environment variables
         QT_ANDROID_KEYSTORE_PATH, and QT_ANDROID_KEYSTORE_ALIAS are used to
         set the values keysotore and alias respectively.
         Also the environment variables QT_ANDROID_KEYSTORE_STORE_PASS,
         and QT_ANDROID_KEYSTORE_KEY_PASS are used to set the store and key
         passwords respectively. This option needs only the --sign parameter.

    --jdk <path/to/jdk>: Used to find the jarsigner tool when used
       in combination with the --release argument. By default,
       an attempt is made to detect the tool using the JAVA_HOME and
       PATH environment variables, in that order.

    --qml-import-paths: Specify additional search paths for QML
       imports.

    --verbose: Prints out information during processing.

    --no-generated-assets-cache: Do not pregenerate the entry list for
       the assets file engine.

    --aux-mode: Operate in auxiliary mode. This will only copy the
       dependencies into the build directory and update the XML templates.
       The project will not be built or installed.

    --apk <path/where/to/copy/the/apk>: Path where to copy the built apk.

    --build-aar: Build an AAR package. This option skips --aab, --install,
       --reinstall, and --sign options if they are provided.

    --qml-importscanner-binary <path/to/qmlimportscanner>: Override the
       default qmlimportscanner binary path. By default the
       qmlimportscanner binary is located using the Qt directory
       specified in the input file.

    --depfile <path/to/depfile>: Output a dependency file.

    --builddir <path/to/build/directory>: build directory. Necessary when
       generating a depfile because ninja requires relative paths.

    --no-rcc-bundle-cleanup: skip cleaning rcc bundle directory after
       running androiddeployqt. This option simplifies debugging of
       the resource bundle content, but it should not be used when deploying
       a project, since it litters the "assets" directory.

    --copy-dependencies-only: resolve application dependencies and stop
       deploying process after all libraries and resources that the
       application depends on have been copied.

    --help: Displays this information.

若指定了project_name ,且希望使用androiddeployqt 构建应用程序包但不将其部署到设备上,请运行以下命令:

androiddeployqt --input <build_dir>/android-project_name-deployment-settings.json \
                --output <build_dir>/android-build

若要构建并将软件包部署到设备上:

androiddeployqt --input <build_dir>/android-project_name-deployment-settings.json \
                --output <build_dir>/android-build --install --device <device_serial_id>

依赖项检测

Qt 自带了许多插件,这些插件会在运行时按需加载。它们可以处理从连接 SQL 数据库到加载特定图像格式等各种任务。 由于插件是在运行时加载的,因此无法检测其依赖关系,但 androiddeployqt 会尝试根据您应用程序的 Qt 依赖关系来推测这些依赖关系。如果某个插件的 Qt 依赖关系中包含您应用程序未依赖的项,则该插件默认不会被包含。 例如,为了确保包含 SVG 图像格式插件,您需要将 Qt SVG 模块,使其成为应用程序的依赖项:

find_package(Qt6 REQUIRED COMPONENTS Svg)
...
target_link_libraries(target_name PRIVATE Qt6::Svg)

如果您想知道为什么某个特定插件没有被自动包含,可以使用--verbose 选项运行androiddeployqt,以获取每个被排除插件的缺失依赖项列表。您还可以在Qt Creator 中通过以下路径勾选“Verbose output ”复选框来实现相同效果:Projects >Build Steps >Build Android APK >Advanced Actions 。

您也可以手动指定应用程序的依赖项。有关更多信息,请参阅QT_ANDROID_DEPLOYMENT_DEPENDENCIESCMake 变量。

注意:androiddeployqt 会扫描项目的 QML 文件以收集 QML 导入项。但是,如果您在运行时从 C++ 作为 `QString ` 加载 QML 代码,这可能会导致无法正常工作,因为 androiddeployqt 在部署时无法识别该情况。 为解决此问题,您可以添加一个占位 QML 文件,该文件导入那些在运行时被引用的 QML 模块。

在Qt Creator

Qt Creator 在后台使用androiddeployqt ,并提供简单直观的用户界面来指定各种选项。有关更多信息,请参阅Qt Creator :Android 部署配置。

有关自定义和部署 Qt for Android 应用程序的更多信息,请参阅《在 Android 上部署应用程序》。

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.