跳到主內容

適用於應用開發者的 Swift 包管理器

如何使用 Swift 包管理器管理原生 iOS 或 macOS 依賴項

Flutter 的 Swift 包管理器整合具有多種優勢

  1. 提供對 Swift 包生態系統的訪問。Flutter 外掛可以使用不斷增長的 Swift 包 生態系統。
  2. 簡化 Flutter 安裝。Xcode 包含 Swift 包管理器。如果您的專案使用 Swift 包管理器，您無需安裝 Ruby 和 CocoaPods。

如何啟用 Swift 包管理器

#

Flutter 的 Swift 包管理器支援預設情況下已停用。要啟用它

  1. 升級到最新的 Flutter SDK

    sh
    flutter upgrade

  2. 啟用 Swift 包管理器功能

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

使用 Flutter CLI 執行應用 遷移專案 以新增 Swift 包管理器整合。這將使您的專案下載 Flutter 外掛所依賴的 Swift 包。使用 Swift 包管理器整合的應用需要 Flutter 版本 3.24 或更高版本。要使用舊版本的 Flutter，您需要 移除 Swift 包管理器整合。

對於尚未支援 Swift 包管理器的依賴項，Flutter 將回退到 CocoaPods。

如何停用 Swift 包管理器

#

停用 Swift 包管理器會導致 Flutter 對所有依賴項使用 CocoaPods。但是，Swift 包管理器仍然整合到您的專案中。要完全從專案中移除 Swift 包管理器整合，請按照 如何移除 Swift 包管理器整合 說明進行操作。

為單個專案停用

#

在專案的 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 包管理器。

為所有專案全域性停用

#

執行以下命令

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

這將為當前使用者停用 Swift 包管理器。

如果專案與 Swift 包管理器不相容，所有貢獻者都需要執行此命令。

如何新增 Swift 包管理器整合

#

新增到 Flutter 應用

#

一旦您 啟用 Swift 包管理器，Flutter CLI 會在您使用 CLI 執行應用時嘗試遷移您的專案。此遷移會更新您的 Xcode 專案，以使用 Swift 包管理器新增 Flutter 外掛依賴項。

要遷移您的專案

  1. 啟用 Swift 包管理器.

  2. 使用 Flutter CLI 執行 iOS 應用。

    如果您的 iOS 專案尚未具有 Swift 包管理器整合，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 包管理器整合 中的步驟操作。

[可選] 要檢查您的專案是否已遷移

  1. 在 Xcode 中執行該應用。

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

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

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

一旦您 啟用 Swift 包管理器，Flutter CLI 會在您使用 CLI 執行應用時嘗試遷移您的專案。此遷移會更新您的 Xcode 專案，以使用 Swift 包管理器新增 Flutter 外掛依賴項。

要遷移您的專案

  1. 啟用 Swift 包管理器.

  2. 使用 Flutter CLI 執行 macOS 應用。

    如果您的 macOS 專案尚未具有 Swift 包管理器整合，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 包管理器整合 中的步驟操作。

[可選] 要檢查您的專案是否已遷移

  1. 在 Xcode 中執行該應用。

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

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

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

手動新增到 Flutter 應用

#

一旦您 啟用 Swift 包管理器，Flutter CLI 會嘗試在您使用 CLI 執行應用時遷移您的專案以使用 Swift 包管理器。

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

如果自動遷移失敗，請使用以下步驟手動將 Swift 包管理器整合新增到專案。

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

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

步驟 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 目標並單擊 Add Package。

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

    確保將包新增到 Runner 目標

  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 作為預操作執行，並且 FlutterGeneratedPluginSwiftPackage 是目標依賴項。

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

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

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

一旦您 啟用 Swift 包管理器，Flutter CLI 會嘗試在您使用 CLI 執行應用時遷移您的專案以使用 Swift 包管理器。

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

如果自動遷移失敗，請使用以下步驟手動將 Swift 包管理器整合新增到專案。

在手動遷移之前，提交 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 目標並單擊 Add Package。

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

    確保將包新增到 Runner 目標

  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/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 是目標依賴項。

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

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

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

新增到現有應用（add-to-app）

#

Flutter 的 Swift 包管理器支援不適用於 add-to-app 場景。

要及時瞭解狀態更新，請參閱 flutter#146957。

新增到自定義 Xcode 目標

#

您的 Flutter Xcode 專案可以具有自定義 Xcode 目標 以構建其他產品，例如框架或單元測試。您可以將 Swift 包管理器整合新增到這些自定義 Xcode 目標。

按照 如何手動新增 Swift 包管理器整合 中的步驟操作。

在 步驟 1，專案符號 6 使用您的自定義目標而不是 Flutter 目標。

在 步驟 2，專案符號 6 使用您的自定義目標而不是 Flutter 目標。

如何移除 Swift 包管理器整合

#

要新增 Swift 包管理器整合，Flutter CLI 會遷移您的專案。此遷移會更新您的 Xcode 專案以新增 Flutter 外掛依賴項。

要撤消此遷移

  1. 停用 Swift 包管理器.

  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 目標的 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

    要移除的構建預操作

如何使用需要更高作業系統版本的 Swift 包管理器 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. 請提高你的應用的目標 最低部署目標版本。

    The target's **Minimum Deployments** setting

    目標的 最低部署目標版本 設定

  3. 如果你更新了你的 iOS 應用的 最低部署目標版本，請重新生成 iOS 專案的配置檔案

    sh
    flutter build ios --config-only

  4. 如果你更新了你的 macOS 應用的 最低部署目標版本，請重新生成 macOS 專案的配置檔案

    sh
    flutter build macos --config-only

除非另有說明，此網站上的文件反映了 Flutter 3.38.6。頁面上次更新於 2025-12-08。 檢視原始碼 或 報告問題。