平台说明 - iOS

部署

在 macOS 上，可以通过Qt Creator 完成 Qt for iOS 应用程序的开发、构建、运行和调试。工具链由 Apple 的 Xcode 提供，对目标平台为 iOS 的项目运行 qmake 或 CMake 时，也会生成包含初始应用程序设置的 Xcode 项目文件（.xcodeproj）。由于Qt Creator 并未提供用于管理所有 iOS 平台特定设置的界面，因此有时需要直接在 Xcode 中进行调整。在向 Apple App Store 提交应用程序以供发布之前，检查应用程序是否配置正确尤为重要。

应用程序包

iOS 应用程序通常以自包含的应用程序包形式部署。应用程序包中包含应用程序的可执行文件以及依赖项，例如 Qt 库、插件、翻译文件以及应用程序可能需要的其他资源。

若要使用 CMake 将应用程序构建为应用程序包，请在可执行目标上设置 MACOSX_BUNDLE 属性，如下所示：

qt_add_executable(MyApp)
if(APPLE)
    set_target_properties(MyApp PROPERTIES MACOSX_BUNDLE TRUE)
endif()

使用 qmake 时，默认会生成应用程序包。若要禁用此功能，请在项目文件（.pro ）中设置 `CONFIG -= app_bundle `。

信息属性列表文件

在 iOS 和 macOS 上，信息属性列表文件（Info.plist）用于配置应用程序包。这些配置设置包括：

应用程序显示名称和标识符
必需的设备功能
支持的用户界面方向
图标和启动图像

详情请参阅 iOS 开发者库中关于“信息属性列表文件”的文档。

使用 CMake 创建 Info.plist

如果某个目标的MACOSX_BUNDLE 属性设置为TRUE ，CMake会生成一个默认的Info.plist 文件。遗憾的是，该文件并不适用于iOS项目。

作为替代方案，项目可以使用 `qt_add_executable`，它会自动生成一个包含适用于 iOS 项目默认值的Info.plist 文件。

若要指定自定义的Info.plist ，项目可如下所示设置MACOSX_BUNDLE_INFO_PLIST 目标属性。这样做将禁用qt_add_executable提供的自动文件生成功能，转而使用 CMake 对项目提供的Info.plist 文件的原生处理机制。

qt_add_executable(app)
if(IOS)
    set_target_properties(app
        PROPERTIES MACOSX_BUNDLE_INFO_PLIST "${CMAKE_CURRENT_SOURCE_DIR}/ios/Info.plist")
endif()

有关可为 CMake 执行的模板替换指定的目标属性和变量的信息，请参阅CMake MACOSX_BUNDLE_INFO_PLIST 文档。

使用 QMake 的 Info.plist

运行 qmake 时，会生成一个包含适当默认值的Info.plist 文件。

建议将生成的 Info.plist 替换为您的自定义副本，以防止下次运行 qmake 时被覆盖。您可以在 .pro 文件中通过QMAKE_INFO_PLIST变量定义自定义信息属性列表。

ios {
    QMAKE_INFO_PLIST = ios/Info.plist
}

应用程序资源

对于无法打包到 Qt 资源中的文件，qmake 变量QMAKE_BUNDLE_DATA提供了一种指定要复制到应用程序包中的一组文件的方法。例如：

ios {
    fontFiles.files = $$files(fonts/*.ttf)
    fontFiles.path = fonts
    QMAKE_BUNDLE_DATA += fontFiles
}

在 CMake 中，可以通过以下方式实现相同的效果：

qt_add_executable(app)
file(GLOB_RECURSE font_files CONFIGURE_DEPENDS "fonts/*.ttf")
if(IOS AND font_files)
    target_sources(app PRIVATE ${font_files})
    set_source_files_properties(
        ${font_files}
        PROPERTIES MACOSX_PACKAGE_LOCATION Resources/fonts)
endif()

对于图像资源，另一种方法是利用 Xcode 中的资源目录，可通过 qmake 按以下方式添加：

ios {
    QMAKE_ASSET_CATALOGS += ios/Assets.xcassets
}

使用 CMake：

qt_add_executable(app)
set(asset_catalog_path "ios/Assets.xcassets")
target_sources(app PRIVATE "${asset_catalog_path}")
set_source_files_properties(
    ${asset_catalog_path}
    PROPERTIES MACOSX_PACKAGE_LOCATION Resources)

图标

从 Xcode 13 开始，图标需要添加到资源目录的图标集（通常名为AppIcon ）中。随后，Xcode 会自动更新Info.plist 文件，添加正确的键和值，并将任何必要的图标文件直接复制到应用程序包中。

从 Xcode 14 开始，只需提供一张 1024x1024 像素大小的图片。Xcode 会自动根据该图片生成所有必要的图标。此外，也可以在资源目录中手动指定图片。

有关可指定的图标的详细列表，请参阅“图标文件”。

文件名并不重要，但实际像素尺寸至关重要。为了支持通用 iOS 应用程序，需要以下图片：

AppIcon60x60@2x.png：120 x 120（适用于 iPhone）
AppIcon76x76@2x~ipad.png: 152 x 152（适用于 iPad）
AppIcon167x167.png: 167×167（适用于 iPad Pro）
AppIcon1024x1024.png: 1024 x 1024（适用于 App Store）

Ad-hoc 分发还应在应用程序包中包含以下文件名，以便在 iTunes 中预览应用程序：

iTunesArtwork 512x512
iTunesArtwork@2x 1024x1024

添加图标的最简单方法是按照 Xcode 文档中的《创建资源目录和资源集》进行操作。

使用 CMake 构建项目时，还应指定以下 Xcode 属性，以确保应用图标由 Xcode 生成。

set_target_properties(app_target_name PROPERTIES
    XCODE_ATTRIBUTE_ASSETCATALOG_COMPILER_APPICON_NAME AppIcon)

以下是一个适用于 Xcode 14 的Assets.xcassets/AppIcon.appiconset/Contents.json 文件示例：

{
  "images" : [
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "20x20"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "3x",
      "size" : "20x20"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "29x29"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "3x",
      "size" : "29x29"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "38x38"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "3x",
      "size" : "38x38"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "40x40"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "3x",
      "size" : "40x40"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "60x60"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "3x",
      "size" : "60x60"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "64x64"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "3x",
      "size" : "64x64"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "68x68"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "76x76"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "83.5x83.5"
    },
    {
      "filename" : "AppIcon1024x1024.png",
      "idiom" : "universal",
      "platform" : "ios",
      "size" : "1024x1024"
    }
  ],
  "info" : {
    "author" : "xcode",
    "version" : 1
  }
}

启动屏幕和启动图像

启动画面

每个 iOS 应用都必须提供一个启动屏幕，该屏幕将在应用启动时显示。启动屏幕是一个 Interface Builder 的.xib 文件，也称为故事板文件。有关详细信息，请参阅《指定应用的启动屏幕》。

iOS 9.0 引入了对启动界面的支持。

qmake 和 CMake 都会生成一个名为LaunchScreen.storyboard 的默认启动屏幕。

若要指定自定义启动画面，必须将其复制到应用程序包中，并在Info.plist 文件中将UILaunchStoryboardName 键设置为该启动画面的名称。

自 Qt 6.4 起，Qt 支持通过 CMake 设置自定义启动画面；自 Qt 6.0 起，则支持通过 qmake 设置。

假设启动文件名为Launch.storyboard ，可按以下方式将其添加到Info.plist 中：

<key>UILaunchStoryboardName</key>
<string>Launch</string>

若要使用 qmake 将启动画面复制到应用程序包中，请在项目的 .pro 文件中使用以下代码片段：

ios {
    QMAKE_IOS_LAUNCH_SCREEN = $$PWD/Launch.storyboard
}

使用 CMake 时：

qt_add_executable(app)
if(IOS)
    set_target_properties(app PROPERTIES
        QT_IOS_LAUNCH_SCREEN "${CMAKE_CURRENT_SOURCE_DIR}/Launch.storyboard")
endif()

启动映像

也可以指定启动图片（PNG 文件）来代替启动屏幕。

注意： 不建议使用启动图片，因为自 iOS 13.0 起，对其支持已被废弃。请考虑改用启动屏幕。

启动图片必须复制到应用程序包中，并且必须在Info.plist 文件中使用UILaunchImages 键设置其名称。

必须准备以下图片：

LaunchImage-iOS7-568h@2x.png：640 x 1136
LaunchImage-iOS7-Landscape.png：1024 × 768
LaunchImage-iOS7-Landscape@2x.png：2048 x 1536
LaunchImage-iOS7-Portrait.png：768 x 1024
LaunchImage-iOS7-Portrait@2x.png：1536 × 2048
LaunchImage-iOS7@2x.png：640 x 960

可按以下方式将图片添加到Info.plist ：

<key>UILaunchImages</key>
<array>
    <dict>
        <key>UILaunchImageMinimumOSVersion</key>
        <string>7.0</string>
        <key>UILaunchImageName</key>
        <string>LaunchImage-iOS7</string>
        <key>UILaunchImageOrientation</key>
        <string>Portrait</string>
        <key>UILaunchImageSize</key>
        <string>{320, 568}</string>
    </dict>
    <dict>
        <key>UILaunchImageMinimumOSVersion</key>
        <string>7.0</string>
        <key>UILaunchImageName</key>
        <string>LaunchImage-iOS7</string>
        <key>UILaunchImageOrientation</key>
        <string>Portrait</string>
        <key>UILaunchImageSize</key>
        <string>{320, 480}</string>
    </dict>
</array>
<key>UILaunchImages~ipad</key>
<array>
    <dict>
        <key>UILaunchImageMinimumOSVersion</key>
        <string>7.0</string>
        <key>UILaunchImageName</key>
        <string>LaunchImage-iOS7-Landscape</string>
        <key>UILaunchImageOrientation</key>
        <string>Landscape</string>
        <key>UILaunchImageSize</key>
        <string>{768, 1024}</string>
    </dict>
    <dict>
        <key>UILaunchImageMinimumOSVersion</key>
        <string>7.0</string>
        <key>UILaunchImageName</key>
        <string>LaunchImage-iOS7-Portrait</string>
        <key>UILaunchImageOrientation</key>
        <string>Portrait</string>
        <key>UILaunchImageSize</key>
        <string>{768, 1024}</string>
    </dict>
    <dict>
        <key>UILaunchImageMinimumOSVersion</key>
        <string>7.0</string>
        <key>UILaunchImageName</key>
        <string>LaunchImage-iOS7</string>
        <key>UILaunchImageOrientation</key>
        <string>Portrait</string>
        <key>UILaunchImageSize</key>
        <string>{320, 568}</string>
    </dict>
    <dict>
        <key>UILaunchImageMinimumOSVersion</key>
        <string>7.0</string>
        <key>UILaunchImageName</key>
        <string>LaunchImage-iOS7</string>
        <key>UILaunchImageOrientation</key>
        <string>Portrait</string>
        <key>UILaunchImageSize</key>
        <string>{320, 480}</string>
    </dict>
</array>

若要使用 qmake 将启动图片复制到应用程序包中，请在项目的 .pro 文件中使用以下代码片段：

ios {
    app_launch_images.files = $$files($$PWD/ios/LaunchImage*.png)
    QMAKE_BUNDLE_DATA += app_launch_images
}

使用 CMake 时：

qt_add_executable(app)
file(GLOB_RECURSE launch_images CONFIGURE_DEPENDS "ios/LaunchImage*.png")
if(IOS AND launch_images)
    target_sources(app PRIVATE ${launch_images})
    set_source_files_properties(
        ${launch_images}
        PROPERTIES MACOSX_PACKAGE_LOCATION Resources)
endif()

注意：较早版本的 iOS 支持通过Info.plist 中的UILaunchImageFile 键指定单个启动映像，但自 iOS 10.0 起，该功能已被废弃。

原生图片选择器

如果您的Info.plist 文件中包含NSPhotoLibraryUsageDescription 的条目，qmake 将自动包含一个额外的插件，该插件可启用原生图片选择器的访问功能。

对于 CMake，请通过qt_import_plugins 手动链接原生图片选择器：

qt_import_plugins(app INCLUDE Qt6::QIosOptionalPlugin_NSPhotoLibraryPlugin)

如果您的QFileDialog 文件中设置的目录为：

QStandardPaths::standardLocations(QStandardPaths::PicturesLocation).last();

或者，在 QML 中将FileDialog 中的currentFolder 设置为：

shortcuts.pictures

随后将显示原生图片选择器，以便用户访问相册。

指定支持的 iOS 版本

Apple 平台提供了一种内置方式来声明应用程序支持的操作系统版本，这使得旧版本的平台能够自动显示用户友好的错误信息，提示用户更新操作系统，而不是直接崩溃并显示堆栈跟踪。

表示对特定操作系统版本范围的支持主要涉及以下概念：

部署目标指定了应用程序支持的 macOS 或 iOS 的硬性最低版本。
SDK 版本指定了应用程序支持的 macOS 或 iOS 的软上限版本。

在为 Apple 平台开发应用程序时，您应始终使用开发时可用的最新版本 Xcode 和最新 SDK。在某些平台（如 iOS）上，如果不这样做，您的应用实际上会被 App Store 拒绝。因此，SDK 版本始终大于或等于部署目标。

在为 Apple 平台开发应用程序时，您必须设置部署目标。Xcode 工具链中的各种构建工具（包括但不限于编译器和链接器）均提供了一个标志，可用于设置此值。通过设置部署目标值，您明确声明应用程序必须至少能在该版本的操作系统上运行，且无法在更早版本的操作系统上运行。随后，您需要确保对系统 API 的使用与声明内容相符。由于编译器知晓您的声明，因此能够协助确保这一要求得到执行。

SDK 版本被视为应用程序兼容的操作系统“软上限”——这意味着，如果应用程序是使用某个 SDK 构建的，即使在更新的操作系统版本上，它仍会继续采用该 SDK 的行为模式，因为操作系统会检查二进制文件的加载命令，并通过模拟向后兼容性来支持旧版操作系统。例如，如果一个应用程序是使用 macOS 10.12 SDK 构建的，那么即使在 10.13 及更高版本上，它也会继续采用 10.12 的行为模式。

然而，Mach-O 二进制文件本质上具有前向兼容性。例如，使用 iOS 9 SDK 构建的应用程序在 iOS 10 上运行完全正常，但可能无法采用新版本中某些功能所做的行为变更，除非该应用程序针对该新版 SDK 重新编译。

可以通过编译器和链接器标志将最低操作系统版本嵌入到 Mach-O 二进制文件中，从而向系统表明该版本。此外，必须在应用程序的 app 包中设置LSMinimumSystemVersion 键。该值必须与传递给编译器和链接器的值一致，因为在 macOS 上，这将使操作系统显示一个用户友好的错误对话框，提示应用程序需要更新版的操作系统，而不是显示崩溃对话框。LSMinimumSystemVersion 也是 App Store 用于显示所需操作系统版本的键值；编译器和链接器的标志在此处不起作用。

在大多数情况下，Qt 应用程序都能正常运行。例如，在 qmake 中，Qt 的 mkspecs 会将QMAKE_IOS_DEPLOYMENT_TARGET或QMAKE_MACOSX_DEPLOYMENT_TARGET设置为 Qt 自身支持的最低版本。同样，在 Qbs 中，Qt 模块会将cpp.minimumIosVersion 、cpp.minimumMacosVersion 、cpp.minimumTvosVersion 或cpp.minimumWatchosVersion 设置为 Qt 本身支持的最低版本。

但是，当您手动设置自己的目标版本时必须格外小心。如果您将其设置为高于 Qt 要求的值，并提供了自己的Info.plist 文件，则必须在Info.plist 中添加一个与部署目标值相匹配的LSMinimumSystemVersion 条目，因为操作系统会将LSMinimumSystemVersion 中的值作为权威值。

如果您指定的部署目标值低于 Qt 的要求，当应用程序在 Qt 不支持的旧版本上运行时，几乎肯定会在 Qt 库的某个位置崩溃。因此，请确保实际的构建系统代码反映了实际所需的最低操作系统版本。

发布到 Apple App Store

如《提交应用程序》中所述，您可以验证您的 Qt for iOS 应用程序是否已准备好发布到 App Store。要提交应用程序，您可以使用 Xcode 或 Application Loader（随 Xcode 一起安装）。Qt Creator 不提供用于管理 Xcode 项目配置中所有设置的界面。

应用应在目标支持的 iOS 版本和设备上进行测试。Qt 应用的最低部署目标因 Qt 版本而异。有关详细信息，请参阅“受支持的配置”。

实际的发布流程包括创建分发证书和配置文件、生成应用程序的已签名归档包，以及对其运行一系列验证测试。

有关更多信息，请参阅 iOS 开发者库中的《应用分发指南》。

符号可见性警告

在链接 C++ 库的上下文中，函数和对象被称为符号。符号的可见性可以是“default ”或“hidden ”。

出于性能考虑，Qt 和许多其他库默认使用hidden 可见性来编译其源代码，仅当符号旨在用于用户项目时，才会将其标记为default 可见性。

遗憾的是，当某个库采用hidden 可见性编译，而用户项目的应用程序或库采用default 可见性编译时，Apple 链接器可能会发出警告。

如果项目开发人员希望抑制该警告，则也需要将项目代码构建为hidden 可见性。

在 CMake 中，可以通过在您的CMakeLists.txt 中添加以下代码来实现：

set(CMAKE_CXX_VISIBILITY_PRESET hidden)

在 qmake 中，可通过在您的.pro 文件中添加以下代码来实现：

CONFIG+=hide_symbols

如果项目构建的是库，则库中任何 intended to be used in another library or application 的符号都必须显式地标记为default 可见性。例如，可以通过在这些函数或类上添加Q_DECL_EXPORT 注解来实现。

CMake 中的产品归档问题

由于CMake 中的一个问题，尝试使用 iOS 应用程序创建产品归档可能会失败。

无论是在 Xcode 中通过“Product”→“Archive”菜单项创建归档，还是在命令行中使用 `xcodebuild -archivePath` 命令，都可能出现此问题。

错误信息可能会提及未定义的符号或不存在的文件路径。

要解决此问题，请在尝试创建归档文件之前，确保先构建一个Release 版本的项目。

由 CMake Xcode 项目生成的 xcarchive 中缺少 dSYM 包

由于 Xcode 中的一个错误以及CMake 的某些限制，在 Xcode 的归档任务过程中，由 CMake 生成的 Xcode 项目将无法将应用程序的dSYM 束包含到xcarchive 中。

Qt 提供了一个可选的变通方案，以便将dSYM 软件包包含到xcarchive 中，但这会带来一些取舍。也就是说，以下 CMake 功能将无法正常工作：

任何$<TARGET_FILE:app> 生成器表达式都可能展开为无效路径，该路径无法指向应用程序二进制文件
即使已设置，CMAKE_RUNTIME_OUTPUT_DIRECTORY 变量及其关联的RUNTIME_OUTPUT_DIRECTORY 目标属性也将被忽略
其他未知问题

为缓解上述问题，您可以：

仅在计划生成xcarchive 时启用此解决方法，而在项目开发期间不要启用
确保仅在项目根目录中添加可执行文件和库文件，而不要在add_subdirectory 调用中添加。

要启用此解决方法，请使用以下选项配置项目：

cmake . -DQT_USE_RISKY_DSYM_ARCHIVING_WORKAROUND=ON

或者在调用任何qt_add_executable 或qt_add_library 之前，在项目中设置该变量：

set(QT_USE_RISKY_DSYM_ARCHIVING_WORKAROUND ON)

...

qt_add_executable(app)

从源代码构建 HarmonyOS 版 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.