跳到主内容

面向应用开发者的 Swift Package Manager

如何为原生 iOS 或 macOS 依赖项使用 Swift Package Manager

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 部分下的 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 Package Manager。

为所有项目全局禁用

#

运行以下命令

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

这会为当前用户关闭 Swift Package Manager。

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

如何添加 Swift Package Manager 集成

#

添加到 Flutter 应用

#

一旦您启用了 Swift Package Manager，当您下次使用 CLI 运行应用时，Flutter 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 作为预操作 (pre-action) 运行，且 FlutterGeneratedPluginSwiftPackage 是目标依赖项。

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

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

一旦您启用了 Swift Package Manager，当您下次使用 CLI 运行应用时，Flutter 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 作为预操作 (pre-action) 运行，且 FlutterGeneratedPluginSwiftPackage 是目标依赖项。

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

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

手动添加到 Flutter 应用

#

一旦您启用了 Swift Package Manager，当您下次使用 CLI 运行应用时，Flutter 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 `Runner` target

    确保将包添加到 Runner target

  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 作为预操作 (pre-action) 运行，且 FlutterGeneratedPluginSwiftPackage 是目标依赖项。

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

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

  3. 确保应用可以通过命令行 flutter run 正常运行。

一旦您启用了 Swift Package Manager，当您下次使用 CLI 运行应用时，Flutter 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 `Runner` target

    确保将包添加到 Runner target

  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 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 作为预操作 (pre-action) 运行，且 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 Package Manager 支持不适用于 add-to-app 场景。

要获取最新的状态更新，请查阅 flutter#146957。

添加到自定义 Xcode target

#

您的 Flutter Xcode 项目可以拥有自定义 Xcode targets，以构建额外的产品（如框架或单元测试）。您可以将 Swift Package Manager 集成添加到这些自定义的 Xcode target 中。

遵循如何手动添加 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 `FlutterGeneratedPluginSwiftPackage` to remove

    要移除的 FlutterGeneratedPluginSwiftPackage

  6. 导航到 Runner target 的 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

    要移除的构建预操作

如何使用需要更高 OS 版本的 Swift Package Manager Flutter 插件

#

如果 Swift Package Flutter Manager 插件要求的 OS 版本高于项目要求，您可能会收到类似以下的错误：

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（最低部署版本）目标。

    The target's **Minimum Deployments** setting

    目标 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 3.41.5。页面最后更新于 2026-05-05。 查看源码 或 报告问题。