跳转至正文

面向应用开发者的 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，你就可以 移除 CocoaPods 集成。

How to remove CocoaPods integration

#

Flutter falls back to CocoaPods if any of your project dependencies do not support Swift Package Manager. Ensure that all plugins in your project support Swift Package Manager before removing CocoaPods.

To remove CocoaPods from your project, use the following steps.

  1. To de-integrate CocoaPods from your Xcode projects, run:

    sh
    cd ios
pod deintegrate
cd ..

  2. Delete CocoaPods-related files and directories:

    Delete ios/Podfile, ios/Podfile.lock, the ios/Pods/ directory, and the ios/.symlinks/ directory (if present).

  3. Check your configuration files:

    In ios/Flutter/Debug.xcconfig and ios/Flutter/Release.xcconfig, remove any #include lines referencing Pods/Target Support Files or CocoaPods .xcconfig files if they are still present.

  4. Clean and build your project to verify the migration:

    sh
    flutter clean
flutter pub get
flutter run

To remove CocoaPods from your project, use the following steps.

  1. To de-integrate CocoaPods from your Xcode projects, run:

    sh
    cd macos
pod deintegrate
cd ..

  2. Delete CocoaPods-related files and directories:

    Delete macos/Podfile, the macos/Pods/ directory, and the macos/.symlinks/ directory (if present).

  3. Check your configuration files:

    In macos/Flutter/Flutter-Debug.xcconfig and macos/Flutter/Flutter-Release.xcconfig remove any #include lines referencing Pods/Target Support Files or CocoaPods .xcconfig files if they are still present.

  4. Clean and build your project to verify the migration:

    sh
    flutter clean
flutter pub get
flutter run

如何手动添加 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.47.2 版本。本页面最后更新时间：2026-08-31。查看文档源码 或者 为本页面内容提出建议。