跳到主内容

Flutter 的 Swift Package Manager 集成有诸多优势

  1. 提供对 Swift 包生态系统的访问。Flutter 插件可以使用日益壮大的 Swift 包生态系统。
  2. 简化 Flutter 安装。Xcode 已包含 Swift Package Manager。如果您的项目使用 Swift Package Manager，则无需安装 Ruby 和 CocoaPods。

如何启用 Swift Package Manager

#

Flutter 的 Swift Package Manager 支持默认关闭。要启用它

  1. 升级到最新的 Flutter SDK

    sh
    flutter upgrade

  2. 启用 Swift Package Manager 功能

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

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

对于尚未支持 Swift Package Manager 的依赖项，Flutter 会回退到使用 CocoaPods。

如何禁用 Swift Package Manager

#

禁用 Swift Package Manager 会导致 Flutter 对所有依赖项使用 CocoaPods。但是，Swift Package Manager 仍会集成到您的项目中。要完全从项目中移除 Swift Package Manager 集成，请遵循如何移除 Swift Package Manager 集成的说明。

禁用单个项目

#

在项目的 pubspec.yaml 文件中，于 flutter 部分下，添加 disable-swift-package-manager: true。

pubspec.yaml
yaml
# The following section is specific to Flutter packages.
flutter:
  disable-swift-package-manager: true

这会为该项目的所有贡献者禁用 Swift Package Manager。

全局禁用所有项目

#

运行以下命令

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

这会为当前用户禁用 Swift Package Manager。

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

如何添加 Swift Package Manager 集成

#

添加到 Flutter 应用

#

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

迁移您的项目

  1. 启用 Swift Package Manager.

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

    如果您的 iOS 项目还没有 Swift Package Manager 集成，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 Package Manager 集成中的步骤操作。

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

  1. 在 Xcode 中运行应用。

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

    Ensure Run Prepare Flutter Framework Script runs as a pre-action
    确保 Run Prepare Flutter Framework Script 作为预操作运行

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

迁移您的项目

  1. 启用 Swift Package Manager.

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

    如果您的 macOS 项目还没有 Swift Package Manager 集成，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 Package Manager 集成中的步骤操作。

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

  1. 在 Xcode 中运行应用。

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

    Ensure Run Prepare Flutter Framework Script runs as a pre-action
    确保 Run Prepare Flutter Framework Script 作为预操作运行

手动添加到 Flutter 应用

#

一旦您启用 Swift Package Manager，Flutter CLI 会在您下次使用 CLI 运行应用时尝试迁移您的项目以使用 Swift Package Manager。

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

如果自动迁移失败，请使用以下步骤手动将 Swift Package Manager 集成添加到项目中。

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

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

步骤 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 Target 并点击 **Add Package**。

    Ensure that the package is added to the target
    确保该包已添加到 Runner Target

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

    Ensure that 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 是 Target 依赖项。

    Ensure Run Prepare Flutter Framework Script runs as a pre-action
    确保 Run Prepare Flutter Framework Script 作为预操作运行

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

一旦您启用 Swift Package Manager，Flutter CLI 会在您下次使用 CLI 运行应用时尝试迁移您的项目以使用 Swift Package Manager。

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

如果自动迁移失败，请使用以下步骤手动将 Swift Package Manager 集成添加到项目中。

在手动迁移之前，请提交一个 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 Target 并点击 **Add Package**。

    Ensure that the package is added to the target
    确保该包已添加到 Runner Target

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

    Ensure that 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 Target。

  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 是 Target 依赖项。

    Ensure runs as a pre-action
    确保 Run Prepare Flutter Framework Script 作为预操作运行

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

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

#

Flutter 的 Swift Package Manager 支持不适用于 add-to-app 场景。

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

添加到自定义 Xcode Target

#

您的 Flutter Xcode 项目可以包含自定义 Xcode targets 来构建附加产品，例如 framework 或单元测试。您可以将 Swift Package Manager 集成添加到这些自定义 Xcode targets。

请遵循如何手动将 Swift Package Manager 集成添加到项目中中的步骤。

在步骤 1的列表项 6 中，使用您的自定义 Target 而不是 Flutter Target。

在步骤 2的列表项 6 中，使用您的自定义 Target 而不是 Flutter Target。

如何移除 Swift Package Manager 集成

#

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

撤销此迁移

  1. 禁用 Swift Package Manager.

  2. 清理您的项目

    sh
    flutter clean

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

  4. 导航至项目的 **Package Dependencies**。

  5. 点击 FlutterGeneratedPluginSwiftPackage 包，然后点击 remove。

    The to remove
    要移除的 FlutterGeneratedPluginSwiftPackage

  6. 导航至 Runner Target 的 **Frameworks, Libraries, and Embedded Content**。

  7. 点击 FlutterGeneratedPluginSwiftPackage，然后点击 remove。

    The 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 Package Manager 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. 提高您应用的 **Minimum Deployments** (最低部署版本) Target。

    The target's Minimum Deployments setting
    Target 的 **Minimum Deployments** (最低部署版本) 设置

  3. 如果您更新了 iOS 应用的 **Minimum Deployments** (最低部署版本)，请重新生成 iOS 项目的配置文件。

    sh
    flutter build ios --config-only

  4. 如果您更新了 macOS 应用的 **Minimum Deployments** (最低部署版本)，请重新生成 macOS 项目的配置文件。

    sh
    flutter build macos --config-only

除非另有说明，本网站上的文档反映了 Flutter 的最新稳定版本。页面最后更新于 2025-08-25。 查看源代码 或 报告此页面问题。