跳转至正文

面向应用开发者的 Swift Package Manager

如何使用 Swift Package Manager 管理 iOS 或 macOS 原生依赖

Flutter 的 Swift Package Manager 集成带来多项好处：

  1. Provides access to the Swift package ecosystem. Flutter plugins can use the growing ecosystem of Swift packages.

  2. 可访问 Swift 包生态。Flutter 插件可使用不断增长的 Swift packages（Swift 包）生态。

  3. Simplifies Flutter installation. Xcode includes Swift Package Manager. You don't need to install Ruby and CocoaPods if your project uses Swift Package Manager.

  4. 简化 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 后，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 是目标依赖项。

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

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

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

    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 (or the xcsheme for the flavor used)

  • 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

    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

    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**

    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

    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

    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 (or the xcscheme for the flavor used)

  • 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

    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

    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**

    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

    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

    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 以构建框架或单元测试等产品。你可以为这些自定义 Xcode target 添加 Swift Package Manager 集成。

请按照 How to add Swift Package Manager integration to a project manually（如何手动为项目添加 Swift Package Manager 集成）中的步骤操作。

在 Step 1 的第 6 项中，使用你的自定义 target 而非 Flutter target。

在 Step 2 的第 6 项中，使用你的自定义 target 而非 Flutter target。

如何移除 Swift Package Manager 集成

#

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

要撤销此迁移：

  1. Turn off Swift Package Manager.

  2. Turn off Swift Package Manager（关闭 Swift Package Manager）。

  3. Clean your project:

  4. 清理项目：

    sh
    flutter clean

  5. Open your app (ios/Runner.xcworkspace or macos/Runner.xcworkspace) in Xcode.

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

  7. Navigate to Package Dependencies for the project.

  8. 导航到项目的 Package Dependencies（包依赖）。

  9. Click the FlutterGeneratedPluginSwiftPackage package, then click the remove button.

  10. 点击 FlutterGeneratedPluginSwiftPackage 包，再点击 remove 按钮。

    The `FlutterGeneratedPluginSwiftPackage` to remove

    The FlutterGeneratedPluginSwiftPackage to remove

    要移除的 `FlutterGeneratedPluginSwiftPackage`

    要移除的 FlutterGeneratedPluginSwiftPackage

  11. Navigate to Frameworks, Libraries, and Embedded Content for the Runner target.

  12. 导航到 Runner target 的 Frameworks, Libraries, and Embedded Content（框架、库与嵌入内容）。

  13. Click FlutterGeneratedPluginSwiftPackage, then click the remove button.

  14. 点击 FlutterGeneratedPluginSwiftPackage，再点击 remove 按钮。

    The `FlutterGeneratedPluginSwiftPackage` to remove

    The FlutterGeneratedPluginSwiftPackage to remove

    要移除的 `FlutterGeneratedPluginSwiftPackage`

    要移除的 FlutterGeneratedPluginSwiftPackage

  15. Go to Product > Scheme > Edit Scheme.

  16. 前往 Product > Scheme > Edit Scheme（编辑 Scheme）。

  17. Expand the Build section in the left side bar.

  18. 展开左侧边栏的 Build（构建）部分。

  19. Click Pre-actions.

  20. 点击 Pre-actions（预操作）。

  21. Expand Run Prepare Flutter Framework Script.

  22. 展开 Run Prepare Flutter Framework Script。

  23. Click the delete button.

  24. 点击 delete 按钮。

    The build pre-action to remove

    The build pre-action to remove

    要移除的构建预操作

    要移除的构建预操作

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

#

若 Swift Package Manager Flutter 插件要求的 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. Open your app (ios/Runner.xcworkspace or macos/Runner.xcworkspace) in Xcode.

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

  3. Increase your app's target Minimum Deployments.

  4. 提高应用 target 的 Minimum Deployments（最低部署版本）。

    The target's **Minimum Deployments** setting

    The target's Minimum Deployments setting

    target 的 **Minimum Deployments** 设置

    target 的 Minimum Deployments 设置

  5. If you updated your iOS app's Minimum Deployments, regenerate the iOS project's configuration files:

  6. 若你更新了 iOS 应用的 Minimum Deployments，请重新生成 iOS 项目配置文件：

    sh
    flutter build ios --config-only

  7. If you updated your macOS app's Minimum Deployments, regenerate the macOS project's configuration files:

  8. 若你更新了 macOS 应用的 Minimum Deployments，请重新生成 macOS 项目配置文件：

    sh
    flutter build macos --config-only

除非另有说明，本文档之所提及适用于 Flutter 3.44.0 版本。本页面最后更新时间：2026-06-04。查看文档源码 或者 为本页面内容提出建议。