跳至主要内容
内容

应用开发者指南：Swift Package Manager

内容

Flutter 的 Swift Package Manager 集成具有以下几个优势

  1. 提供对 Swift 包生态系统的访问。Flutter 插件可以使用不断增长的 Swift 包 生态系统。
  2. 简化 Flutter 安装。Xcode 包含 Swift Package Manager。如果您的项目使用 Swift Package Manager，则无需安装 Ruby 和 CocoaPods。

如果您在 Flutter 的 Swift Package Manager 支持中发现错误，请 提交问题。

如何开启 Swift 包管理器

#

Flutter 的 Swift Package Manager 支持默认情况下处于关闭状态。要将其打开

  1. 切换到 Flutter 的 main 渠道

    sh
    flutter channel main --no-cache-artifacts

  2. 升级到最新的 Flutter SDK 并下载构件

    sh
    flutter upgrade

  3. 启用 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 包管理器

#

禁用 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 包管理器集成

#

添加到 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（或使用的风味的 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 框架脚本预操作

#

必须为每个风味完成以下步骤。

  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（或使用的风味的 xcscheme）

步骤 1：添加 FlutterGeneratedPluginSwiftPackage 包依赖项

#

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

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

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

  3. 点击 add。

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

  5. 导航到 macos/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 框架脚本预操作

#

必须为每个风味完成以下步骤。

  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 支持不适用于添加到应用的场景。

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

添加到自定义 Xcode 目标

#

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

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

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

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

如何移除 Swift 包管理器集成

#

要添加 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

要使用该插件，请增加应用目标的 最低部署版本。

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

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