跳转至正文

面向应用开发者的 Swift Package Manager

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

如何启用 Swift Package Manager

#

自 3.44 版本起，Flutter 默认启用 Swift Package Manager (SwiftPM) 支持。升级 Flutter 并运行应用会自动添加 SwiftPM 集成，这会让你的项目下载 Flutter 插件所依赖的 Swift package。若要使用较旧版本的 Flutter，你可能需要从应用中 移除 Swift Package Manager 集成。

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

[可选] 检查你的项目是否正在使用 SwiftPM：

  1. 在 Xcode 中运行应用。

  2. 确保 Run Prepare Flutter Framework Script 作为 pre-action 运行，且 FlutterGeneratedPluginSwiftPackage 是一个 target 依赖项。

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

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

如果你之前禁用过 SwiftPM，可能需要使用 flutter config --enable-swift-package-manager 来启用。

如果自动迁移对你有效，那就大功告成了！本页内容到此结束。

如何手动添加 Swift Package Manager 集成

#

当你升级到 Flutter 3.44 或更高版本并运行应用时， SwiftPM 集成会自动添加。只有当出现问题、你需要手动为项目添加 SwiftPM 集成时，才需要参考这些说明。

大多数开发者无需这样做。

如果在将项目自动迁移到 SwiftPM 的过程中遇到问题，请 提交一个 issue。请附上错误信息，如有可能，还请在 issue 中附上以下文件的副本：

  • ios/Runner.xcodeproj/project.pbxproj

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

迁移到 SwiftPM，需要更新 ios/Runner.xcodeproj/project.pbxproj和 ios/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme 文件。

步骤 1：添加 FlutterGeneratedPluginSwiftPackage package 依赖

#

  1. 在 Xcode 中打开 ios/Runner.xcworkspace。

  2. 导航到项目的 Package Dependencies（package 依赖）。

    The project's package dependencies

    The project's package dependencies

  3. 点击 add 按钮。

  4. 在打开的对话框中，点击 Add Local...（添加本地…）。

  5. 导航到 ios/Flutter/ephemeral/Packages/FlutterGeneratedPluginSwiftPackage，然后点击 Add Package（添加 Package）。

  6. 确保已添加到 Runner 目标，然后点击 Add Package（添加 Package）。

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

    Ensure that the package is added to the Runner target

  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

步骤 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

步骤 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

  3. 确保应用在命令行中可通过 flutter run 运行。

迁移到 SwiftPM，需要更新 ios/Runner.xcodeproj/project.pbxproj和 ios/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme 文件。

步骤 1：添加 FlutterGeneratedPluginSwiftPackage package 依赖

#

  1. 在 Xcode 中打开 macos/Runner.xcworkspace。

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

    The project's package dependencies

    The project's package dependencies

  3. 点击 add 按钮。

  4. 在打开的对话框中，点击 Add Local...（添加本地…）。

  5. 导航到 macos/Flutter/ephemeral/Packages/FlutterGeneratedPluginSwiftPackage，然后点击 Add Package（添加 Package）。

  6. 确保已添加到 Runner 目标，然后点击 Add Package（添加 Package）。

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

    Ensure that the package is added to the Runner target

  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

步骤 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

步骤 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

  3. 确保应用在命令行中可通过 flutter run 运行。

添加到现有应用 (add-to-app)

#

要使用 SwiftPM，请根据需要参阅以下页面之一：

添加到自定义 Xcode target

#

Flutter Xcode 项目可有自定义 Xcode targets 以构建框架或单元测试等产品。你可以为这些自定义 Xcode target 添加 Swift Package Manager 集成。

请按照 如何添加 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（Package 依赖）。

  5. 点击 FlutterGeneratedPluginSwiftPackage package，再点击 remove 按钮。

    The `FlutterGeneratedPluginSwiftPackage` to remove

    The FlutterGeneratedPluginSwiftPackage to remove

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

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

    The `FlutterGeneratedPluginSwiftPackage` to remove

    The FlutterGeneratedPluginSwiftPackage to remove

  8. 前往 Product > Scheme > Edit Scheme。

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

  10. 点击 Pre-actions。

  11. 展开 Run Prepare Flutter Framework Script。

  12. 点击 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. 在 Xcode 中打开应用（ios/Runner.xcworkspace 或 macos/Runner.xcworkspace）。

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

    The target's **Minimum Deployments** setting

    The target's Minimum Deployments setting

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

    sh
    flutter build ios --config-only

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

    sh
    flutter build macos --config-only

如何关闭 Swift Package Manager

#

一般情况下，请不要这样做。请记住， CocoaPods registry 将于 2026 年 12 月 2 日变为只读，今后将不再允许禁用 SwiftPM。

禁用 Swift Package Manager 会让 Flutter 对所有依赖项都使用 CocoaPods。不过，SwiftPM 仍会保持与项目的集成。若要将 Swift Package Manager 集成从项目中彻底移除，请按照 如何移除 Swift Package Manager 集成 中的说明操作。

为单个项目关闭 SwiftPM

#

在项目的 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。

为所有项目全局关闭 SwiftPM

#

运行以下命令：

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

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

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

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