跳到主内容

适用于应用开发者的 Swift 包管理器

如何使用 Swift 包管理器管理原生 iOS 或 macOS 依赖项

Flutter 的 Swift 包管理器集成具有多种优势

  1. 提供对 Swift 包生态系统的访问。Flutter 插件可以使用不断增长的 Swift 包 生态系统。
  2. 简化 Flutter 安装。Xcode 包含 Swift 包管理器。如果您的项目使用 Swift 包管理器，您无需安装 Ruby 和 CocoaPods。

如何启用 Swift 包管理器

#

Flutter 的 Swift 包管理器支持默认情况下已禁用。要启用它

  1. 升级到最新的 Flutter SDK

    sh
    flutter upgrade

  2. 启用 Swift 包管理器功能

    sh
    flutter config --enable-swift-package-manager

使用 Flutter CLI 运行应用 迁移项目 以添加 Swift 包管理器集成。这将使您的项目下载 Flutter 插件所依赖的 Swift 包。使用 Swift 包管理器集成的应用需要 Flutter 版本 3.24 或更高版本。要使用旧版本的 Flutter，您需要 移除 Swift 包管理器集成。

对于尚未支持 Swift 包管理器的依赖项，Flutter 将回退到 CocoaPods。

如何禁用 Swift 包管理器

#

禁用 Swift 包管理器会导致 Flutter 对所有依赖项使用 CocoaPods。但是，Swift 包管理器仍然集成到您的项目中。要完全从项目中移除 Swift 包管理器集成，请按照 如何移除 Swift 包管理器集成 说明进行操作。

为单个项目禁用

#

在项目的 pubspec.yaml 文件中，在 flutter 部分下，在 config 子部分中将 enable-swift-package-manager 设置为 false。

pubspec.yaml
yaml 
# The following section is specific to Flutter packages.
flutter:
  config:
    enable-swift-package-manager: false

这将为该项目的所有贡献者禁用 Swift 包管理器。

为所有项目全局禁用

#

运行以下命令

sh 
flutter config --no-enable-swift-package-manager

这将为当前用户禁用 Swift 包管理器。

如果项目与 Swift 包管理器不兼容，所有贡献者都需要运行此命令。

如何添加 Swift 包管理器集成

#

添加到 Flutter 应用

#

一旦您 启用 Swift 包管理器，Flutter CLI 会在您使用 CLI 运行应用时尝试迁移您的项目。此迁移会更新您的 Xcode 项目，以使用 Swift 包管理器添加 Flutter 插件依赖项。

要迁移您的项目

  1. 启用 Swift 包管理器.

  2. 使用 Flutter CLI 运行 iOS 应用。

    如果您的 iOS 项目尚未具有 Swift 包管理器集成，Flutter CLI 会尝试迁移您的项目并输出类似如下内容

    flutter run
Adding Swift Package Manager integration...

    自动 iOS 迁移会修改 ios/Runner.xcodeproj/project.pbxproj 和 ios/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme 文件。

  3. 如果 Flutter CLI 的自动迁移失败，请按照 手动添加 Swift 包管理器集成 中的步骤操作。

[可选] 要检查您的项目是否已迁移

  1. 在 Xcode 中运行该应用。

  2. 确保 Run Prepare Flutter Framework Script 作为预操作运行，并且 FlutterGeneratedPluginSwiftPackage 是目标依赖项。

    Ensure **Run Prepare Flutter Framework Script** runs as a pre-action

    确保 Run Prepare Flutter Framework Script 作为预操作运行

一旦您 启用 Swift 包管理器，Flutter CLI 会在您使用 CLI 运行应用时尝试迁移您的项目。此迁移会更新您的 Xcode 项目，以使用 Swift 包管理器添加 Flutter 插件依赖项。

要迁移您的项目

  1. 启用 Swift 包管理器.

  2. 使用 Flutter CLI 运行 macOS 应用。

    如果您的 macOS 项目尚未具有 Swift 包管理器集成，Flutter CLI 会尝试迁移您的项目并输出类似如下内容

    flutter run -d macos
Adding Swift Package Manager integration...

    自动 iOS 迁移会修改 macos/Runner.xcodeproj/project.pbxproj 和 macos/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme 文件。

  3. 如果 Flutter CLI 的自动迁移失败，请按照 手动添加 Swift 包管理器集成 中的步骤操作。

[可选] 要检查您的项目是否已迁移

  1. 在 Xcode 中运行该应用。

  2. 确保 Run Prepare Flutter Framework Script 作为预操作运行，并且 FlutterGeneratedPluginSwiftPackage 是目标依赖项。

    Ensure **Run Prepare Flutter Framework Script** runs as a pre-action

    确保 Run Prepare Flutter Framework Script 作为预操作运行

手动添加到 Flutter 应用

#

一旦您 启用 Swift 包管理器，Flutter CLI 会尝试在您使用 CLI 运行应用时迁移您的项目以使用 Swift 包管理器。

但是，如果存在意外的修改，Flutter CLI 工具可能无法自动迁移您的项目。

如果自动迁移失败，请使用以下步骤手动将 Swift 包管理器集成添加到项目。

在手动迁移之前，提交 issue；这有助于 Flutter 团队改进自动迁移过程。在您的 issue 中包含错误消息，如果可能，请包含以下文件的副本

  • ios/Runner.xcodeproj/project.pbxproj
  • ios/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme（或所用 flavor 的 xcsheme）

步骤 1：添加 FlutterGeneratedPluginSwiftPackage 包依赖项

#

  1. 在 Xcode 中打开您的应用 (ios/Runner.xcworkspace)。

  2. 导航到项目的 Package Dependencies。

    The project's package dependencies

    项目的包依赖项

  3. 单击 add 按钮。

  4. 在打开的对话框中，单击 Add Local...。

  5. 导航到 ios/Flutter/ephemeral/Packages/FlutterGeneratedPluginSwiftPackage 并单击 Add Package。

  6. 确保将其添加到 Runner 目标并单击 Add Package。

    Ensure that the package is added to the `Runner` target

    确保将包添加到 Runner 目标

  7. 确保 FlutterGeneratedPluginSwiftPackage 已添加到 Frameworks, Libraries, and Embedded Content。

    Ensure that `FlutterGeneratedPluginSwiftPackage` was added to **Frameworks, Libraries, and Embedded Content**

    确保 FlutterGeneratedPluginSwiftPackage 已添加到 Frameworks, Libraries, and Embedded Content

步骤 2：添加 Run Prepare Flutter Framework Script 预操作

#

必须为每个 flavor 完成以下步骤。

  1. 转到 Product > Scheme > Edit Scheme。

  2. 在左侧边栏中展开 Build 部分。

  3. 单击 Pre-actions。

  4. 单击 add 按钮，然后从菜单中选择 New Run Script Action。

  5. 单击 Run Script 标题并将其更改为

    Run Prepare Flutter Framework Script

  6. 将 Provide build settings from 更改为 Runner 应用。

  7. 在文本框中输入以下内容

    sh
    "$FLUTTER_ROOT/packages/flutter_tools/bin/xcode_backend.sh" prepare
    Add **Run Prepare Flutter Framework Script** build pre-action

    添加 Run Prepare Flutter Framework Script 构建预操作

步骤 3：运行应用

#

  1. 在 Xcode 中运行该应用。

  2. 确保 Run Prepare Flutter Framework Script 作为预操作运行，并且 FlutterGeneratedPluginSwiftPackage 是目标依赖项。

    Ensure **Run Prepare Flutter Framework Script** runs as a pre-action

    确保 Run Prepare Flutter Framework Script 作为预操作运行

  3. 确保应用在命令行中使用 flutter run 运行。

一旦您 启用 Swift 包管理器，Flutter CLI 会尝试在您使用 CLI 运行应用时迁移您的项目以使用 Swift 包管理器。

但是，如果存在意外的修改，Flutter CLI 工具可能无法自动迁移您的项目。

如果自动迁移失败，请使用以下步骤手动将 Swift 包管理器集成添加到项目。

在手动迁移之前，提交 issue；这有助于 Flutter 团队改进自动迁移过程。在您的 issue 中包含错误消息，如果可能，请包含以下文件的副本

  • macos/Runner.xcodeproj/project.pbxproj
  • macos/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme（或所用 flavor 的 xcscheme）

步骤 1：添加 FlutterGeneratedPluginSwiftPackage 包依赖项

#

  1. 在 Xcode 中打开您的应用 (macos/Runner.xcworkspace)。

  2. 导航到项目的 Package Dependencies。

    The project's package dependencies

    项目的包依赖项

  3. 单击 add 按钮。

  4. 在打开的对话框中，单击 Add Local...。

  5. 导航到 macos/Flutter/ephemeral/Packages/FlutterGeneratedPluginSwiftPackage 并单击 Add Package。

  6. 确保将其添加到 Runner 目标并单击 Add Package。

    Ensure that the package is added to the `Runner` target

    确保将包添加到 Runner 目标

  7. 确保 FlutterGeneratedPluginSwiftPackage 已添加到 Frameworks, Libraries, and Embedded Content。

    Ensure that `FlutterGeneratedPluginSwiftPackage` was added to **Frameworks, Libraries, and Embedded Content**

    确保 FlutterGeneratedPluginSwiftPackage 已添加到 Frameworks, Libraries, and Embedded Content

步骤 2：添加 Run Prepare Flutter Framework Script 预操作

#

必须为每个 flavor 完成以下步骤。

  1. 转到 Product > Scheme > Edit Scheme。

  2. 在左侧边栏中展开 Build 部分。

  3. 单击 Pre-actions。

  4. 单击 add 按钮，然后从菜单中选择 New Run Script Action。

  5. 单击 Run Script 标题并将其更改为

    Run Prepare Flutter Framework Script

  6. 将 Provide build settings from 更改为 Runner 目标。

  7. 在文本框中输入以下内容

    sh
    "$FLUTTER_ROOT"/packages/flutter_tools/bin/macos_assemble.sh prepare
    Add **Run Prepare Flutter Framework Script** build pre-action

    添加 Run Prepare Flutter Framework Script 构建预操作

步骤 3：运行应用

#

  1. 在 Xcode 中运行该应用。

  2. 确保 Run Prepare Flutter Framework Script 作为预操作运行，并且 FlutterGeneratedPluginSwiftPackage 是目标依赖项。

    Ensure `Run Prepare Flutter Framework Script` runs as a pre-action

    确保 Run Prepare Flutter Framework Script 作为预操作运行

  3. 确保应用在命令行中使用 flutter run 运行。

添加到现有应用（add-to-app）

#

Flutter 的 Swift 包管理器支持不适用于 add-to-app 场景。

要及时了解状态更新，请参阅 flutter#146957。

添加到自定义 Xcode 目标

#

您的 Flutter Xcode 项目可以具有自定义 Xcode 目标 以构建其他产品，例如框架或单元测试。您可以将 Swift 包管理器集成添加到这些自定义 Xcode 目标。

按照 如何手动添加 Swift 包管理器集成 中的步骤操作。

在 步骤 1，项目符号 6 使用您的自定义目标而不是 Flutter 目标。

在 步骤 2，项目符号 6 使用您的自定义目标而不是 Flutter 目标。

如何移除 Swift 包管理器集成

#

要添加 Swift 包管理器集成，Flutter CLI 会迁移您的项目。此迁移会更新您的 Xcode 项目以添加 Flutter 插件依赖项。

要撤消此迁移

  1. 禁用 Swift 包管理器.

  2. 清理您的项目

    sh
    flutter clean

  3. 在 Xcode 中打开您的应用 (ios/Runner.xcworkspace 或 macos/Runner.xcworkspace)。

  4. 导航到项目的 Package Dependencies。

  5. 单击 FlutterGeneratedPluginSwiftPackage 包，然后单击 remove 按钮。

    The `FlutterGeneratedPluginSwiftPackage` to remove

    要移除的 FlutterGeneratedPluginSwiftPackage

  6. 导航到 Runner 目标的 Frameworks, Libraries, and Embedded Content。

  7. 单击 FlutterGeneratedPluginSwiftPackage，然后单击 remove 按钮。

    The `FlutterGeneratedPluginSwiftPackage` to remove

    要移除的 FlutterGeneratedPluginSwiftPackage

  8. 转到 Product > Scheme > Edit Scheme。

  9. 在左侧边栏中展开 Build 部分。

  10. 单击 Pre-actions。

  11. 展开 Run Prepare Flutter Framework Script。

  12. 单击 delete 按钮。

    The build pre-action to remove

    要移除的构建预操作

如何使用需要更高操作系统版本的 Swift 包管理器 Flutter 插件

#

如果 Swift Package Flutter Manager 插件需要比项目更高的操作系统版本，你可能会收到如下错误

Target Integrity (Xcode): The package product 'plugin_name_ios' requires minimum platform version 14.0 for the iOS platform, but this target supports 12.0

要使用该插件

  1. 在 Xcode 中打开您的应用 (ios/Runner.xcworkspace 或 macos/Runner.xcworkspace)。

  2. 请提高你的应用的目标 最低部署目标版本。

    The target's **Minimum Deployments** setting

    目标的 最低部署目标版本 设置

  3. 如果你更新了你的 iOS 应用的 最低部署目标版本，请重新生成 iOS 项目的配置文件

    sh
    flutter build ios --config-only

  4. 如果你更新了你的 macOS 应用的 最低部署目标版本，请重新生成 macOS 项目的配置文件

    sh
    flutter build macos --config-only

除非另有说明，此网站上的文档反映了 Flutter 3.38.6。页面上次更新于 2025-12-08。 查看源代码 或 报告问题。