跳至主要內容

Flutter 整合 Swift Package Manager 有以下幾項優點：

  1. 可存取 Swift 套件生態系。 Flutter 套件（plugins）可以利用日益壯大的 Swift 套件 生態系。
  2. 簡化 Flutter 安裝流程。 Xcode 已內建 Swift Package Manager。 如果你的專案使用 Swift Package Manager，就不需要安裝 Ruby 與 CocoaPods。

How to turn on Swift Package Manager

#

Flutter's Swift Package Manager support is turned off by default. To turn it on:

  1. Upgrade to the latest Flutter SDK:

    sh
    flutter upgrade

  2. Turn on the Swift Package Manager feature:

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

Using the Flutter CLI to run an app migrates the project to add Swift Package Manager integration. This makes your project download the Swift packages that your Flutter plugins depend on. An app with Swift Package Manager integration requires Flutter version 3.24 or higher. To use an older Flutter version, you will need to remove Swift Package Manager integration from the app.

Flutter falls back to CocoaPods for dependencies that do not support Swift Package Manager yet.

How to turn off Swift Package Manager

#

Disabling Swift Package Manager causes Flutter to use CocoaPods for all dependencies. However, Swift Package Manager remains integrated with your project. To remove Swift Package Manager integration completely from your project, follow the How to remove Swift Package Manager integration instructions.

Turn off for a single project

#

In the project's pubspec.yaml file, under the flutter section, add disable-swift-package-manager: true.

pubspec.yaml
yaml
# The following section is specific to Flutter packages.
flutter:
  disable-swift-package-manager: true

This turns off Swift Package Manager for all contributors to this project.

Turn off globally for all projects

#

Run the following command:

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

This turns off Swift Package Manager for the current user.

If a project is incompatible with Swift Package Manager, all contributors need to run this command.

如何新增 Swift Package Manager 整合

#

新增至 Flutter 應用程式

#

Once you turn on Swift Package Manager, the Flutter CLI tries to migrate your project the next time you run your app using the CLI. This migration updates your Xcode project to use Swift Package Manager to add Flutter plugin dependencies.

To migrate your project:

  1. Turn on Swift Package Manager.

  2. Run the iOS app using the Flutter CLI.

    If your iOS project doesn't have Swift Package Manager integration yet, the Flutter CLI tries to migrate your project and outputs something like:

    flutter run
Adding Swift Package Manager integration...

    The automatic iOS migration modifies the ios/Runner.xcodeproj/project.pbxproj and ios/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme files.

  3. If the Flutter CLI's automatic migration fails, follow the steps in add Swift Package Manager integration manually.

[Optional] To check if your project is migrated:

  1. Run the app in Xcode.

  2. Ensure that Run Prepare Flutter Framework Script runs as a pre-action and that FlutterGeneratedPluginSwiftPackage is a target dependency.

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

Once you turn on Swift Package Manager, the Flutter CLI tries to migrate your project the next time you run your app using the CLI. This migration updates your Xcode project to use Swift Package Manager to add Flutter plugin dependencies.

To migrate your project:

  1. Turn on Swift Package Manager.

  2. Run the macOS app using the Flutter CLI.

    If your macOS project doesn't have Swift Package Manager integration yet, the Flutter CLI tries to migrate your project and outputs something like:

    flutter run -d macos
Adding Swift Package Manager integration...

    The automatic iOS migration modifies the macos/Runner.xcodeproj/project.pbxproj and macos/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme files.

  3. If the Flutter CLI's automatic migration fails, follow the steps in add Swift Package Manager integration manually.

[Optional] To check if your project is migrated:

  1. Run the app in Xcode.

  2. Ensure that Run Prepare Flutter Framework Script runs as a pre-action and that FlutterGeneratedPluginSwiftPackage is a target dependency.

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

手動 新增至 Flutter 應用程式

#

Once you turn on Swift Package Manager, the Flutter CLI tries to migrate your project to use Swift Package Manager the next time you run your app using the CLI.

However, the Flutter CLI tool might be unable to migrate your project automatically if there are unexpected modifications.

If the automatic migration fails, use the steps below to add Swift Package Manager integration to a project manually.

Before migrating manually, file an issue; this helps the Flutter team improve the automatic migration process. Include the error message and, if possible, include a copy of the following files in your issue:

  • ios/Runner.xcodeproj/project.pbxproj
  • ios/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme (or the xcsheme for the flavor used)

Step 1: Add FlutterGeneratedPluginSwiftPackage Package Dependency

#

  1. Open your app (ios/Runner.xcworkspace) in Xcode.

  2. Navigate to Package Dependencies for the project.

    The project's package dependenciesThe project's package dependencies

  3. Click add.

  4. In the dialog that opens, click Add Local....

  5. Navigate to ios/Flutter/ephemeral/Packages/FlutterGeneratedPluginSwiftPackage and click Add Package.

  6. Ensure that it's added to the Runner target and click Add Package.

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

  7. Ensure that FlutterGeneratedPluginSwiftPackage was added to 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

Step 2: Add Run Prepare Flutter Framework Script Pre-Action

#

The following steps must be completed for each flavor.

  1. Go to Product > Scheme > Edit Scheme.

  2. Expand the Build section in the left side bar.

  3. Click Pre-actions.

  4. Click add and select New Run Script Action from the menu.

  5. Click the Run Script title and change it to:

    Run Prepare Flutter Framework Script

  6. Change the Provide build settings from to the Runner app.

  7. Input the following in the text box:

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

    Add **Run Prepare Flutter Framework Script** build pre-actionAdd Run Prepare Flutter Framework Script build pre-action

Step 3: Run app

#

  1. Run the app in Xcode.

  2. Ensure that Run Prepare Flutter Framework Script runs as a pre-action and that FlutterGeneratedPluginSwiftPackage is a target dependency.

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

  3. Ensure that the app runs on the command line with flutter run.

Once you turn on Swift Package Manager, the Flutter CLI tries to migrate your project to use Swift Package Manager the next time you run your app using the CLI.

However, the Flutter CLI tool might be unable to migrate your project automatically if there are unexpected modifications.

If the automatic migration fails, use the steps below to add Swift Package Manager integration to a project manually.

Before migrating manually, file an issue; this helps the Flutter team improve the automatic migration process. Include the error message and, if possible, include a copy of the following files in your issue:

  • macos/Runner.xcodeproj/project.pbxproj
  • macos/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme (or the xcscheme for the flavor used)

Step 1: Add FlutterGeneratedPluginSwiftPackage Package Dependency

#

  1. Open your app (macos/Runner.xcworkspace) in Xcode.

  2. Navigate to Package Dependencies for the project.

    The project's package dependenciesThe project's package dependencies

  3. Click add.

  4. In the dialog that opens, click the Add Local....

  5. Navigate to macos/Flutter/ephemeral/Packages/FlutterGeneratedPluginSwiftPackage and click the Add Package.

  6. Ensure that it's added to the Runner Target and click Add Package.

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

  7. Ensure that FlutterGeneratedPluginSwiftPackage was added to 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

Step 2: Add Run Prepare Flutter Framework Script Pre-Action

#

The following steps must be completed for each flavor.

  1. Go to Product > Scheme > Edit Scheme.

  2. Expand the Build section in the left side bar.

  3. Click Pre-actions.

  4. Click the add button and select New Run Script Action from the menu.

  5. Click the Run Script title and change it to:

    Run Prepare Flutter Framework Script

  6. Change the Provide build settings from to the Runner target.

  7. Input the following in the text box:

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

    Add **Run Prepare Flutter Framework Script** build pre-actionAdd Run Prepare Flutter Framework Script build pre-action

Step 3: Run app

#

  1. Run the app in Xcode.

  2. Ensure that Run Prepare Flutter Framework Script runs as a pre-action and that FlutterGeneratedPluginSwiftPackage is a target dependency.

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

  3. Ensure that the app runs on the command line with flutter run.

新增至現有應用程式（add-to-app）

#

Flutter 的 Swift Package Manager 支援目前不適用於 add-to-app 情境。

若想掌握最新狀態，請參考 flutter#146957。

新增至自訂 Xcode target

#

你的 Flutter Xcode 專案可以擁有自訂的 Xcode targets，用來建置額外產品，例如 framework 或單元測試。 你可以將 Swift Package Manager 整合新增至這些自訂 Xcode target。

請依照 如何手動將 Swift Package Manager 整合新增至專案 的步驟操作。

在 步驟 1，第 6 項，請使用你的自訂 target 取代 Flutter target。

在 步驟 2，第 6 項，請使用你的自訂 target 取代 Flutter target。

如何移除 Swift Package Manager 整合

#

為了新增 Swift Package Manager 整合，Flutter CLI 會遷移你的專案。 這個遷移會更新你的 Xcode 專案，以加入 Flutter 套件（plugin）相依性。

若要還原這個遷移：

  1. 關閉 Swift Package Manager。

  2. 清理你的專案：

    sh
    flutter clean

  3. 在 Xcode 中開啟你的應用程式（ios/Runner.xcworkspace 或 macos/Runner.xcworkspace）。

  4. 前往專案的 Package Dependencies（套件相依性）。

  5. 點選 FlutterGeneratedPluginSwiftPackage 套件，然後點擊 remove。

    要移除的 `FlutterGeneratedPluginSwiftPackage`要移除的 FlutterGeneratedPluginSwiftPackage

  6. 前往 Runner target 的 Frameworks, Libraries, and Embedded Content（框架、程式庫與嵌入內容）。

  7. 點選 FlutterGeneratedPluginSwiftPackage，然後點擊 remove。

    要移除的 `FlutterGeneratedPluginSwiftPackage`要移除的 FlutterGeneratedPluginSwiftPackage

  8. 前往 Product > Scheme > Edit Scheme。

  9. 在左側邊欄展開 Build 區段。

  10. 點選 Pre-actions（預先動作）。

  11. 展開 Run Prepare Flutter Framework Script。

  12. 點選 delete。

    要移除的建置前動作要移除的建置前動作

如何使用需要較高作業系統版本的 Swift Package Manager Flutter 插件

#

如果某個 Swift Package Manager Flutter 插件所需的作業系統版本高於你的專案設定，可能會出現如下錯誤：

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. 提高您的應用程式目標的Minimum Deployments（最低部署版本）設定。

    目標的 **Minimum Deployments** 設定目標的 Minimum Deployments 設定

  3. 如果您已更新 iOS 應用程式的 Minimum Deployments，請重新產生 iOS 專案的組態檔案：

    sh
    flutter build ios --config-only

  4. 如果你已更新 macOS 應用程式的最低部署版本（Minimum Deployments），
    請重新產生 macOS 專案的設定檔案：

    sh
    flutter build macos --config-only

除非另有說明，本網站上的文件反映最新的 Flutter 穩定版。頁面最後更新於 2025-10-26。 檢視原始碼 或 回報問題.