构建优化版 Qt
本页面介绍了如何根据您的具体需求，配置并构建一个更小且经过定制的 Qt 版本。
步骤 1：获取源代码、安装构建依赖项并设置环境
有关获取源代码、安装依赖项和设置环境的信息，请参阅各平台的具体说明：
- Windows 版 Qt - 从源代码构建
- macOS 版 Qt - 从源代码构建
- Linux 版 Qt - 从源代码构建
- 配置嵌入式 Linux 设备
- Android 版 Qt - 从源代码构建
- 适用于 iOS 的 Qt - 从源代码构建
步骤 2：构建 Qt 库和工具
请遵循您所用平台的具体说明，并使用以下Qt 配置选项来创建一个针对您需求进行优化的构建。
下表详细介绍了有助于缩小构建大小的 configure 选项。
| Qt 配置选项 | 说明 |
|---|---|
| -static | 生成用于静态链接的归档文件。 静态二进制文件会将所有必要的库和依赖项嵌入可执行文件本身中。这意味着运行程序时，它会使用自身内部的所需库副本，而非依赖外部库。这使得链接器能够舍弃二进制代码中不必要的部分。对于单个可执行文件的发布而言，这是最优的解决方案。 |
| -ltcg | 链接时优化（LTO）是一种强大的技术，它通过在链接阶段分析和优化二进制代码，可以显著提高性能并减小可执行文件的大小。 |
| -reduce-exports | 减少导出符号的数量。 |
| -gc-binaries | 从二进制文件中移除不必要的部分。将每个函数或数据项放置在各自的段中，并启用链接器对未使用段的垃圾回收。 |
| -submodules qtbase,qtdeclarative,qtqmlscriptcompiler,qtsvg | 待编译的子模块。将依赖项限制在非必要功能范围内。 |
| -skip qtlanguageserver,qtquicktimeline | 从编译中移除自动包含的子模块。将依赖项限制为非必需功能。 |
| -disable-deprecated-up-to <版本> | 移除已弃用的实现。 将QT_DISABLE_DEPRECATED_UP_TO 的值设置为<version>。QT_DISABLE_DEPRECATED_UP_TO 用于从API和ABI中移除已弃用的方法。<version>是一个十六进制值。 例如，使用 0x070000 可移除 Qt 7.0.0 或更早版本中所有已弃用的代码。默认情况下，Windows 系统和非 Windows 系统中，<version> 分别设置为 0x040000 和 0x050000。 |
此外，您还可以按照“包含或排除功能”中的说明逐一移除功能。这可能会对可用组件和功能造成限制。并非所有组合都经过测试。 Qt Test 在持续集成（CI）系统中测试了特定的最小化 `configure` 选项组合；它测试了高度精简的嵌入式 Linux 配置，以及针对其他平台的稍不那么精简的配置。这些配置旨在运行 Qt Quick 应用程序。
Qt 的 configure 命令还支持-- （双破折号）命令行参数，允许用户注入额外的 CMake 参数，例如 -DCMAKE_CXX_FLAGS="-march=native"。 在交叉编译的情况下，如“工具链文件示例”中所述，可通过 -DCMAKE_TOOLCHAIN_FILE=path/to/toolchain.cmake 添加这些参数。下表列出了您在 GCC 中可以考虑使用的一些选项：
| 编译器选项 | 说明 |
|---|---|
| -march <arch> | 目标架构。如果应用程序在与编译时相同的架构上运行，请使用“native”。 |
| -mtune <tune> | 指示编译器生成能够充分利用指定处理器架构特性的代码，例如其指令集、寄存器数量和缓存层次结构。 |
| -fno-asynchronous-unwind-tables | 减小二进制文件大小。请注意，禁用异步展开表可能会对代码的性能、兼容性和可维护性产生影响。通常建议仅在必要时使用此选项，且需在仔细权衡其潜在影响后方可使用。 |
| -fno-unwind-tables | 减小二进制文件大小。请注意，禁用展开表可能会影响代码的性能、兼容性和可维护性。通常建议仅在必要时使用此选项，并需仔细权衡其潜在影响。 值得注意的是， |
| -fomit-frame-pointer | 可减小二进制文件大小。启用此选项后，编译器不会为每次函数调用在栈中存储帧指针，而是直接使用栈指针作为帧指针，从而节省内存并提升性能。 值得注意的是，某些编译器（如 GCC 和 Clang）在针对特定架构（如 ARM 和 PowerPC）编译时，或在某些优化模式下，会默认启用 `-fomit-frame-pointer `。 |
| -fno-exceptions | 缩小二进制文件大小。启用此选项后，编译器不会为 try-catch 代码块生成代码，且任何抛出或捕获异常的尝试都会导致运行时错误。Qt 本身可在不使用异常的情况下运行，但某些依赖项可能需要异常。 |
| -no-pie | 减小二进制文件大小。通常，应谨慎使用位置无关代码（-fno-pie ），且仅在必要时使用，因为它可能会影响编译后代码的兼容性和性能。位置无关可执行文件还能增强安全性。有关位置无关代码的更多信息，请参阅维基百科中的“地址空间布局随机化（ASLR）”条目。 |
下表列出了链接器选项：
| 链接器选项 | 描述 |
|---|---|
| -no-pie | 减小二进制文件大小。通常应谨慎使用-fno-pie ，且仅在必要时使用，因为它可能会影响编译后代码的兼容性和性能。位置无关的可执行文件还能增强安全性。有关位置无关代码的更多信息，请参阅维基百科中的“地址空间布局随机化”。 |
步骤 3：构建应用程序
安装 Qt 后，即可开始使用它构建应用程序。
使用 CMake 项目命令优化 QML 代码生成。有关 QML 代码生成的更多信息，请参阅qt_add_qml_module以及《QML 和Qt Quick 的最佳实践》。
以下 CMake 代码片段中的命令可减小二进制文件的大小：
set_target_properties(
ExampleApp
PROPERTIES
QT_QMLCACHEGEN_ARGUMENTS "--only-bytecode"
)如果您计划通过 IDE 构建应用程序，则需要在 IDE 中显式注册 Qt 版本：
- 关于Qt Creator ，请参阅Qt Creator ：添加 Qt 版本。
- 对于Qt Extension for Visual Studio Code ，请参阅Qt Extension for Visual Studio Code ：注册 Qt 安装。
如果您使用命令行构建应用程序，请遵循特定平台的指南。
© 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.
