跳到主內容

面向應用開發者的 Swift Package Manager

如何為原生 iOS 或 macOS 依賴項使用 Swift Package Manager

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 部分下的 config 子部分中，將 enable-swift-package-manager 設定為 false。

pubspec.yaml
yaml 
# The following section is specific to Flutter packages.
flutter:
  config:
    enable-swift-package-manager: false

這會為該專案的所有貢獻者關閉 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. 確保 Run Prepare Flutter Framework Script 作為預操作 (pre-action) 執行，且 FlutterGeneratedPluginSwiftPackage 是目標依賴項。

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

    確保 Run Prepare Flutter Framework Script 作為預操作執行

一旦您啟用了 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. 確保 Run Prepare Flutter Framework Script 作為預操作 (pre-action) 執行，且 FlutterGeneratedPluginSwiftPackage 是目標依賴項。

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

    確保 Run Prepare Flutter Framework Script 作為預操作執行

手動新增到 Flutter 應用

#

一旦您啟用了 Swift Package Manager，當您下次使用 CLI 執行應用時，Flutter 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 `Runner` target

    確保將包新增到 Runner target

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

    Ensure that `FlutterGeneratedPluginSwiftPackage` 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 作為預操作 (pre-action) 執行，且 FlutterGeneratedPluginSwiftPackage 是目標依賴項。

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

    確保 Run Prepare Flutter Framework Script 作為預操作執行

  3. 確保應用可以透過命令列 flutter run 正常執行。

一旦您啟用了 Swift Package Manager，當您下次使用 CLI 執行應用時，Flutter 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 `Runner` target

    確保將包新增到 Runner target

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

    Ensure that `FlutterGeneratedPluginSwiftPackage` 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 作為預操作 (pre-action) 執行，且 FlutterGeneratedPluginSwiftPackage 是目標依賴項。

    Ensure `Run Prepare Flutter Framework Script` 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，以構建額外的產品（如框架或單元測試）。您可以將 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 外掛依賴項。

要撤銷此遷移：

  1. 關閉 Swift Package Manager.

  2. 清理您的專案

    sh
    flutter clean

  3. 在 Xcode 中開啟您的應用 (ios/Runner.xcworkspace 或 macos/Runner.xcworkspace)。

  4. 導航到專案的 Package Dependencies（包依賴項）。

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

    The `FlutterGeneratedPluginSwiftPackage` to remove

    要移除的 FlutterGeneratedPluginSwiftPackage

  6. 導航到 Runner target 的 Frameworks, Libraries, and Embedded Content。

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

    The `FlutterGeneratedPluginSwiftPackage` 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

    要移除的構建預操作

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

要使用該外掛：

  1. 在 Xcode 中開啟您的應用 (ios/Runner.xcworkspace 或 macos/Runner.xcworkspace)。

  2. 提高您應用的 Minimum Deployments（最低部署版本）目標。

    The target's **Minimum Deployments** setting

    目標 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 3.41.5。頁面最後更新於 2026-05-05。 檢視原始碼 或 報告問題。