跳到主内容

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，下次使用 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. 确保 运行 Flutter 框架准备脚本 作为预操作运行，并且 FlutterGeneratedPluginSwiftPackage 是目标依赖项。

    Ensure Run Prepare Flutter Framework Script runs as a pre-action
    确保 运行 Flutter 框架准备脚本 作为预操作运行

一旦您启用 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. 确保 运行 Flutter 框架准备脚本 作为预操作运行，并且 FlutterGeneratedPluginSwiftPackage 是目标依赖项。

    Ensure Run Prepare Flutter Framework Script runs as a pre-action
    确保 运行 Flutter 框架准备脚本 作为预操作运行

手动添加到 Flutter 应用

#

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

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

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

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

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

步骤 1：添加 FlutterGeneratedPluginSwiftPackage 包依赖项

#

  1. 在 Xcode 中打开您的应用 (ios/Runner.xcworkspace)。

  2. 导航到项目的 包依赖项。

    The project's package dependencies
    项目的包依赖项

  3. 点击 add。

  4. 在打开的对话框中，点击 添加本地...。

  5. 导航到 ios/Flutter/ephemeral/Packages/FlutterGeneratedPluginSwiftPackage，然后点击 添加包。

  6. 确保将其添加到 Runner 目标，然后点击 添加包。

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

  7. 确保 FlutterGeneratedPluginSwiftPackage 已添加到 框架、库和嵌入式内容 中。

    Ensure that was added to Frameworks, Libraries, and Embedded Content
    确保 FlutterGeneratedPluginSwiftPackage 已添加到 框架、库和嵌入式内容

步骤 2：添加运行 Flutter 框架准备脚本预操作

#

以下步骤必须针对每个 flavor 完成。

  1. 转到 产品 > 方案 > 编辑方案。

  2. 展开左侧边栏中的 构建 部分。

  3. 点击 预操作。

  4. 点击 add，然后从菜单中选择 新建运行脚本操作。

  5. 点击 运行脚本 标题并将其更改为

    Run Prepare Flutter Framework Script

  6. 将 提供构建设置来源 更改为 Runner 应用。

  7. 在文本框中输入以下内容

    sh
    "$FLUTTER_ROOT/packages/flutter_tools/bin/xcode_backend.sh" prepare

    Add Run Prepare Flutter Framework Script build pre-action
    添加 运行 Flutter 框架准备脚本 构建预操作

步骤 3：运行应用

#

  1. 在 Xcode 中运行应用。

  2. 确保 运行 Flutter 框架准备脚本 作为预操作运行，并且 FlutterGeneratedPluginSwiftPackage 是目标依赖项。

    Ensure Run Prepare Flutter Framework Script runs as a pre-action
    确保 运行 Flutter 框架准备脚本 作为预操作运行

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

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

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

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

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

  • macos/Runner.xcodeproj/project.pbxproj
  • macos/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme（或所用 flavor 的 xcsheme 文件）

步骤 1：添加 FlutterGeneratedPluginSwiftPackage 包依赖项

#

  1. 在 Xcode 中打开您的应用 (macos/Runner.xcworkspace)。

  2. 导航到项目的 包依赖项。

    The project's package dependencies
    项目的包依赖项

  3. 点击 add。

  4. 在打开的对话框中，点击 添加本地...。

  5. 导航到 macos/Flutter/ephemeral/Packages/FlutterGeneratedPluginSwiftPackage，然后点击 添加包。

  6. 确保将其添加到 Runner Target，然后点击 添加包。

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

  7. 确保 FlutterGeneratedPluginSwiftPackage 已添加到 框架、库和嵌入式内容 中。

    Ensure that was added to Frameworks, Libraries, and Embedded Content
    确保 FlutterGeneratedPluginSwiftPackage 已添加到 框架、库和嵌入式内容

步骤 2：添加运行 Flutter 框架准备脚本预操作

#

以下步骤必须针对每个 flavor 完成。

  1. 转到 产品 > 方案 > 编辑方案。

  2. 展开左侧边栏中的 构建 部分。

  3. 点击 预操作。

  4. 点击 add 按钮，然后从菜单中选择 新建运行脚本操作。

  5. 点击 运行脚本 标题并将其更改为

    Run Prepare Flutter Framework Script

  6. 将 提供构建设置来源 更改为 Runner 目标。

  7. 在文本框中输入以下内容

    sh
    "$FLUTTER_ROOT"/packages/flutter_tools/bin/macos_assemble.sh prepare

    Add Run Prepare Flutter Framework Script build pre-action
    添加 运行 Flutter 框架准备脚本 构建预操作

步骤 3：运行应用

#

  1. 在 Xcode 中运行应用。

  2. 确保 运行 Flutter 框架准备脚本 作为预操作运行，并且 FlutterGeneratedPluginSwiftPackage 是目标依赖项。

    Ensure runs as a pre-action
    确保 运行 Flutter 框架准备脚本 作为预操作运行

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

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

#

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

要了解最新状态更新，请查阅 flutter#146957。

添加到自定义 Xcode 目标

#

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

请按照如何手动将 Swift Package Manager 集成添加到项目中的步骤进行操作。

在步骤 1 的第 6 项中，使用您的自定义目标而不是 Flutter 目标。

在步骤 2 的第 6 项中，使用您的自定义目标而不是 Flutter 目标。

如何移除 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. 导航到项目的 包依赖项。

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

    The to remove
    要移除的 FlutterGeneratedPluginSwiftPackage

  6. 导航到 Runner 目标的 框架、库和嵌入式内容。

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

    The to remove
    要移除的 FlutterGeneratedPluginSwiftPackage

  8. 转到 产品 > 方案 > 编辑方案。

  9. 展开左侧边栏中的 构建 部分。

  10. 点击 预操作。

  11. 展开 运行 Flutter 框架准备脚本。

  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. 增加应用目标的 最低部署。

    The target's Minimum Deployments setting
    目标的 最低部署 设置

  3. 如果您更新了 iOS 应用的 最低部署，请重新生成 iOS 项目的配置文件

    sh
    flutter build ios --config-only

  4. 如果您更新了 macOS 应用的 最低部署，请重新生成 macOS 项目的配置文件

    sh
    flutter build macos --config-only

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