跳到主內容

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，Flutter CLI 會在您下次使用 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. 確保 Run Prepare Flutter Framework Script 作為預操作執行，並且 FlutterGeneratedPluginSwiftPackage 是 Target 依賴項。

    Ensure Run Prepare Flutter Framework Script runs as a pre-action
    確保 Run Prepare Flutter Framework Script 作為預操作執行

一旦您啟用 Swift Package Manager，Flutter CLI 會在您下次使用 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. 確保 Run Prepare Flutter Framework Script 作為預操作執行，並且 FlutterGeneratedPluginSwiftPackage 是 Target 依賴項。

    Ensure Run Prepare Flutter Framework Script runs as a pre-action
    確保 Run Prepare Flutter Framework Script 作為預操作執行

手動新增到 Flutter 應用

#

一旦您啟用 Swift Package Manager，Flutter CLI 會在您下次使用 CLI 執行應用時嘗試遷移您的專案以使用 Swift Package Manager。

然而，如果存在意外修改，Flutter CLI 工具可能無法自動遷移您的專案。

如果自動遷移失敗，請使用以下步驟手動將 Swift Package Manager 整合新增到專案中。

在手動遷移之前，請提交一個 issue；這有助於 Flutter 團隊改進自動遷移過程。請在 issue 中包含錯誤訊息，如果可能，請附上以下檔案的副本：

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

步驟 1：新增 FlutterGeneratedPluginSwiftPackage 包依賴

#

  1. 在 Xcode 中開啟您的應用（ios/Runner.xcworkspace）。

  2. 導航至專案的 **Package Dependencies**。

    The project's package dependencies
    專案的包依賴項

  3. 點選 add。

  4. 在開啟的對話方塊中，點選 **Add Local...**。

  5. 導航至 ios/Flutter/ephemeral/Packages/FlutterGeneratedPluginSwiftPackage 並點選 **Add Package**。

  6. 確保它已新增到 Runner Target 並點選 **Add Package**。

    Ensure that the package is added to the target
    確保該包已新增到 Runner Target

  7. 確保 FlutterGeneratedPluginSwiftPackage 已新增到 **Frameworks, Libraries, and Embedded Content**。

    Ensure that was added to Frameworks, Libraries, and Embedded Content
    確保 FlutterGeneratedPluginSwiftPackage 已新增到 **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
    新增 **Run Prepare Flutter Framework Script** 構建預操作

步驟 3：執行應用

#

  1. 在 Xcode 中執行應用。

  2. 確保 Run Prepare Flutter Framework Script 作為預操作執行，並且 FlutterGeneratedPluginSwiftPackage 是 Target 依賴項。

    Ensure Run Prepare Flutter Framework Script runs as a pre-action
    確保 Run Prepare Flutter Framework Script 作為預操作執行

  3. 確保應用在命令列中使用 flutter run 執行。

一旦您啟用 Swift Package Manager，Flutter CLI 會在您下次使用 CLI 執行應用時嘗試遷移您的專案以使用 Swift Package Manager。

然而，如果存在意外修改，Flutter CLI 工具可能無法自動遷移您的專案。

如果自動遷移失敗，請使用以下步驟手動將 Swift Package Manager 整合新增到專案中。

在手動遷移之前，請提交一個 issue；這有助於 Flutter 團隊改進自動遷移過程。請在 issue 中包含錯誤訊息，如果可能，請附上以下檔案的副本：

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

步驟 1：新增 FlutterGeneratedPluginSwiftPackage 包依賴

#

  1. 在 Xcode 中開啟您的應用（macos/Runner.xcworkspace）。

  2. 導航至專案的 **Package Dependencies**。

    The project's package dependencies
    專案的包依賴項

  3. 點選 add。

  4. 在開啟的對話方塊中，點選 **Add Local...**。

  5. 導航至 macos/Flutter/ephemeral/Packages/FlutterGeneratedPluginSwiftPackage 並點選 **Add Package**。

  6. 確保它已新增到 Runner Target 並點選 **Add Package**。

    Ensure that the package is added to the target
    確保該包已新增到 Runner Target

  7. 確保 FlutterGeneratedPluginSwiftPackage 已新增到 **Frameworks, Libraries, and Embedded Content**。

    Ensure that was added to Frameworks, Libraries, and Embedded Content
    確保 FlutterGeneratedPluginSwiftPackage 已新增到 **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 Target。

  7. 在文字框中輸入以下內容

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

    Add Run Prepare Flutter Framework Script build pre-action
    新增 **Run Prepare Flutter Framework Script** 構建預操作

步驟 3：執行應用

#

  1. 在 Xcode 中執行應用。

  2. 確保 Run Prepare Flutter Framework Script 作為預操作執行，並且 FlutterGeneratedPluginSwiftPackage 是 Target 依賴項。

    Ensure runs as a pre-action
    確保 Run Prepare Flutter Framework Script 作為預操作執行

  3. 確保應用在命令列中使用 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 targets。

請遵循如何手動將 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**。

  5. 點選 FlutterGeneratedPluginSwiftPackage 包，然後點選 remove。

    The to remove
    要移除的 FlutterGeneratedPluginSwiftPackage

  6. 導航至 Runner Target 的 **Frameworks, Libraries, and Embedded Content**。

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

    The to remove
    要移除的 FlutterGeneratedPluginSwiftPackage

  8. 轉到 **Product > Scheme > Edit Scheme**。

  9. 在左側邊欄展開 **Build** 部分。

  10. 點選 **Pre-actions**。

  11. 展開 **Run Prepare Flutter Framework Script**。

  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. 提高您應用的 **Minimum Deployments** (最低部署版本) Target。

    The target's Minimum Deployments setting
    Target 的 **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-08-25。 檢視原始碼 或 報告此頁面問題。