Skip to main content
Contents

应用开发者指南：Swift Package Manager

Contents

:::警告 Flutter 正在迁移到Swift Package Manager来管理iOS和macOS原生依赖项。 Flutter对Swift Package Manager的支持正在开发中。 如果您在Flutter的Swift Package Manager支持中发现错误，请提交问题。 Swift Package Manager支持默认关闭。 Flutter继续支持CocoaPods。 :::

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
# 下面部分特定于 Flutter 包。
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
正在添加 Swift Package Manager 集成...

    自动 iOS 迁移会修改 ios/Runner.xcodeproj/project.pbxproj 和 ios/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme 文件。

  3. 如果 Flutter CLI 的自动迁移失败，请按照手动添加 Swift Package Manager 集成中的步骤操作。

[可选] 要检查您的项目是否已迁移：

  1. 在 Xcode 中运行应用。

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

    确保 运行准备 Flutter 框架脚本 作为预操作运行
    确保 运行准备 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
正在添加 Swift Package Manager 集成...

    自动 iOS 迁移会修改 macos/Runner.xcodeproj/project.pbxproj 和 macos/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme 文件。

  3. 如果 Flutter CLI 的自动迁移失败，请按照手动添加 Swift Package Manager 集成 中的步骤操作。

[可选] 要检查您的项目是否已迁移：

  1. 在 Xcode 中运行应用程序。

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

    确保 运行准备 Flutter 框架脚本 作为预操作运行
    确保 运行准备 Flutter 框架脚本 作为预操作运行

手动添加到Flutter应用

#

启用Swift Package Manager后，下次您使用命令行工具运行应用时，Flutter 命令行工具会尝试将您的项目迁移到使用 Swift Package Manager。

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

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

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

  • ios/Runner.xcodeproj/project.pbxproj
  • ios/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme （或所用版本的 xcscheme）

步骤 1：添加 FlutterGeneratedPluginSwiftPackage 包依赖项

#

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

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

    项目的包依赖项
    项目的包依赖项

  3. 点击 add。

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

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

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

    确保将包添加到 目标
    确保将包添加到 Runner 目标

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

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

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

#

必须为每个版本完成以下步骤。

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

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

  3. 点击 预操作 。

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

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

    运行准备 Flutter 框架脚本

  6. 将 从以下提供构建设置 更改为 Runner 应用。

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

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

    添加运行准备 Flutter 框架脚本构建预操作
    添加运行准备 Flutter 框架脚本构建预操作

步骤 3：运行应用

#

  1. 在 Xcode 中运行应用。

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

    确保运行准备 Flutter 框架脚本作为预操作运行
    确保运行准备 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 （或所用版本的 xcscheme）

步骤 1：添加 FlutterGeneratedPluginSwiftPackage 包依赖项

#

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

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

    项目的包依赖项
    项目的包依赖项

  3. 点击 add。

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

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

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

    确保该包已添加到 目标
    确保该包已添加到 Runner 目标

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

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

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

#

必须为每个版本完成以下步骤。

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

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

  3. 点击 预操作 。

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

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

    运行准备 Flutter 框架脚本

  6. 将 从以下提供构建设置 更改为 Runner 目标。

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

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

    添加运行准备 Flutter 框架脚本构建预操作
    添加运行准备 Flutter 框架脚本构建预操作

步骤 3：运行应用

#

  1. 在 Xcode 中运行应用。

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

    确保 作为预操作运行
    确保 运行准备 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. 导航到项目的Package Dependencies。

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

    要移除的
    要移除的FlutterGeneratedPluginSwiftPackage

  6. 导航到Runner目标的Frameworks, Libraries, and Embedded Content。

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

    要移除的
    要移除的FlutterGeneratedPluginSwiftPackage

  8. 前往Product > Scheme > Edit Scheme。

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

  10. 点击Pre-actions。

  11. 展开Run Prepare Flutter Framework Script。

  12. 点击**delete**。

要移除的构建预操作
要移除的构建预操作

如何使用需要更高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

要使用该插件，请增加应用目标的Minimum Deployments。

目标的Minimum Deployments设置
目标的Minimum Deployments设置

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