# 将 Flutter 应用集成到 macOS 项目

> 了解如何将 Flutter 应用集成到你现有的 macOS 项目中。



:::note
As of the 3.44 release, Flutter uses [Swift Package Manager][]
to manage iOS and macOS native dependencies.
Flutter continues to support CocoaPods in maintenance mode,
however, the CocoaPods registry permanently becomes
[read-only on December 2, 2026][cocoapods].

自 Flutter 3.44 起，Flutter 使用 [Swift Package Manager][]，
来管理 iOS 和 macOS 的原生依赖项。
CocoaPods 已正式进入维护模式，
其 registry 将 [于 2026 年 12 月 2 日永久变为只读][cocoapods]。
:::

[cocoapods]: https://blog.cocoapods.org/CocoaPods-Specs-Repo/
[Swift Package Manager]: https://www.swift.org/documentation/package-manager/

Flutter UI components can be incrementally added
into your existing macOS application using Swift packages.

可使用 Swift package 将 Flutter UI 组件逐步添加到你现有的 macOS 应用中。

## Prerequisites

## 前提条件

* Flutter 3.44 or later

  Flutter 3.44 或更高版本

* Xcode 15.0 or later

  Xcode 15.0 或更高版本

### Migrate from legacy integration (if applicable) {: #migrate-legacy-integration}

### 从旧版集成迁移（如适用） {: #migrate-legacy-integration}

If you've already integrated Flutter into your macOS app
using embedded frameworks,
you must first remove that integration
before following the Swift Package Manager instructions below.

若你已使用嵌入 framework 将 Flutter 集成到 macOS 应用，
须先移除该集成，再按下方 Swift Package Manager 说明操作。

<details>
  <summary>展开查看从嵌入 framework 集成迁移的说明</summary>

  If your app was previously integrated using frameworks
  generated by the `flutter build macos-framework` command,
  you must first remove the frameworks from your Xcode project.

  若应用此前通过 `flutter build macos-framework` 命令生成的 framework 集成，
  须先从 Xcode 项目中移除这些 framework。

  1. Navigate to your target's **General** tab
     and remove all Flutter-related frameworks and libraries
     under **Frameworks, Libraries, and Embedded Content**.

     进入 target 的 **General** 标签页，
     在 **Frameworks, Libraries, and Embedded Content** 下
     移除所有与 Flutter 相关的 framework 与库。

       This includes the `App.xcframework`, `FlutterMacOS.xcframework`,
       `FlutterPluginRegistrant.xcframework`,
       and any Flutter plugins' `xcframework` files.

       包括 `App.xcframework`、`FlutterMacOS.xcframework`、`FlutterPluginRegistrant.xcframework` 
       以及所有 Flutter 插件的 `xcframework` 文件。

  1. Remove the Flutter pod from your Podfile

     从 Podfile 中移除 Flutter pod

      ```ruby title="MyApp/Podfile" diff
      - pod 'FlutterMacOS', :podspec => '/path/to/MyApp/Flutter/[build mode]/FlutterMacOS.podspec'
      ```

   1. Run `pod install`.

      运行 `pod install`。

</details>

### Organize your projects relative to each other {: #organize-projects-relatively}

### 相对组织项目结构 {: #organize-projects-relatively}

This guide assumes that your existing macOS app
and your Flutter app reside in sibling directories.
If you have a different directory structure,
you will need to adjust the example relative paths accordingly.

本指南假定现有 macOS 应用与 Flutter 应用位于同级目录。
若目录结构不同，须相应调整示例中的相对路径。

:::note

If integrating for the first time,
run the following command to create a new Flutter application:

若首次集成，运行以下命令创建新的 Flutter 应用：

```console
flutter create my_flutter_app
```

:::

The example directory structure resembles the following:

示例目录结构如下：

<FileTree>

- my_flutter_app/
  - macos/
  - lib/
    - main.dart
- MyNativeApp/
  - MyNativeApp.xcodeproj/

</FileTree>

## Integrate with Swift Package Manager {: #integrate-with-swiftpm}

## 使用 Swift Package Manager 集成 {: #integrate-with-swiftpm}

 1. <h3>Build the FlutterNativeIntegration Swift package</h3>

    <h3>构建 FlutterNativeIntegration Swift package</h3>

    Within your Flutter application or module, run the following command:

    在 Flutter 应用或模块中运行以下命令：

    ```console
    flutter build swift-package --platform macos
    ```

    This generates the following directories:

    将生成以下目录：

    <FileTree>

    - my_flutter_app/build/macos/SwiftPackages/
      - FlutterNativeIntegration/ (A Swift package)
      - Scripts/ (Directory of scripts and other files needed)

    </FileTree>

    You can optionally change the location of this output
    with the `--output` flag.

    你可使用 `--output` 标志可选地更改输出位置。

 1. <h3>Add FlutterNativeIntegration to your Xcode project</h3>

    <h3>将 FlutterNativeIntegration 添加到 Xcode 项目</h3>

    1. In the Project navigator, right click on your project
       and select **Add Files to "MyNativeApp"...**

       在 Project navigator 中右键项目，选择 **Add Files to "MyNativeApp"...**

    1. Navigate to and select the generated
       `FlutterNativeIntegration` Swift package and click **Add**.

       找到并选择生成的 `FlutterNativeIntegration` Swift package，点击 **Add**。

    1. Select **Reference files in place** and click **Finish**.

       选择 **Reference files in place**，点击 **Finish**。

    1. In the File inspector,
       verify the **Location** is **Relative to Project**.
       If it is not, you'll need to move the Flutter output directory
       to be a sibling directory of your native app.

       在 File inspector 中确认 **Location** 为 **Relative to Project**。
       若不是，须将 Flutter 输出目录移至与原生应用同级的目录。

       <DashImage image="development/add-to-app/macos/project-setup-swiftpm/flutternativeintegration-relative-location.png" caption="Relative location of FlutterNativeIntegration shown in Xcode's File inspector." />

    1. Navigate to your target's **General** tab
       and add `FlutterNativeIntegration` under
       **Frameworks, Libraries, and Embedded Content**.

       进入 target 的 **General** 标签页，
       在 **Frameworks, Libraries, and Embedded Content** 下添加 `FlutterNativeIntegration`。

       <DashImage image="development/add-to-app/ios/project-setup-swiftpm/flutternativeintegration-library.png" caption="FlutterNativeIntegration under Frameworks, Libraries, and Embedded Content." />

 1. <h3>Add build settings</h3>

    <h3>添加构建设置</h3>

    1. In the **Build Settings** tab,
       set the location of the Flutter app's Swift package output directory:

       在 **Build Settings** 标签页中设置 Flutter 应用 Swift package 输出目录位置：

       ```
       FLUTTER_SWIFT_PACKAGE_OUTPUT=$SRCROOT/../my_flutter_app/build/macos/SwiftPackages
       ```

    1. For custom configurations, set the Flutter build mode.

       对于自定义配置，设置 Flutter 构建模式。

       Flutter supports three [build modes][]: Debug, Profile, and Release.
       The build mode is determined using the `CONFIGURATION` value.
       If your configuration does not match one of these,
       you can set the `FLUTTER_BUILD_MODE` build setting
       to one of these values.

       Flutter 支持三种 [构建模式][build modes]：Debug、Profile 与 Release。
       构建模式由 `CONFIGURATION` 值决定。
       若配置不匹配其中任一，可将 `FLUTTER_BUILD_MODE` 构建设置设为这些值之一。

       <DashImage image="development/add-to-app/ios/project-setup-swiftpm/flutter-build-mode.png" caption="Setting `FLUTTER_BUILD_MODE` for custom configurations under **Build Settings**." />

    1. For **Debug** configurations only, set the following build settings:

       仅对 **Debug** 配置设置以下构建设置：

       ```
       ENABLE_APP_SANDBOX=YES
       ENABLE_INCOMING_NETWORK_CONNECTIONS=YES
       RUNTIME_EXCEPTION_ALLOW_JIT=YES
       ```

       <DashImage image="development/add-to-app/macos/project-setup-swiftpm/allow-jit-build-setting.png" caption="Set **Allow JIT** (RUNTIME_EXCEPTION_ALLOW_JIT) to **YES** in the target's **Build Settings** for **Debug** configurations only." />

    1. (Optional) Allow Xcode to re-build your Flutter app.

       （可选）允许 Xcode 重新构建 Flutter 应用。

       Add the following build settings to your target
       to allow Xcode to re-build your Flutter app as part of its build.
       This allows you to make changes to your Flutter application
       without needing to re-run `flutter build swift-package`.
       This requires a Flutter installation on the machine.

       向 target 添加以下构建设置，使 Xcode 在构建过程中重新构建 Flutter 应用。
       这样修改 Flutter 应用后无需重新运行 `flutter build swift-package`。
       这要求机器上已安装 Flutter。

       ```
       FLUTTER_APPLICATION_PATH=$SRCROOT/../my_flutter_app
       ENABLE_USER_SCRIPT_SANDBOXING=NO
       ```

       :::tip
       This only re-builds the Flutter app's code.
       If you add new dependencies,
       you'll need to re-run `flutter build swift-package`.

       这仅重新构建 Flutter 应用的代码。
       若添加新依赖，
       需要重新运行 `flutter build swift-package`。
       :::

 1. <h3>Add Pre-action Run Script to Scheme</h3>

    <h3>向 Scheme 添加 Pre-action Run Script</h3>

    1. Open **Product** &gt; **Scheme** &gt; **Edit Scheme...**
       &gt; **Build** (in left side bar) &gt; **Pre-action** &gt; **+**
       &gt; **New Run Script Action**

       打开 **Product** &gt; **Scheme** &gt; **Edit Scheme...** 
       &gt; **Build**（左侧边栏）&gt; **Pre-action** &gt; **+** 
       &gt; **New Run Script Action**

    1. Select your project in the **Provide build settings from** dropdown.

       在 **Provide build settings from** 下拉菜单中选择项目。

    1. Set the script to the following:

       将脚本设置为：

       ```
       /bin/sh $FLUTTER_SWIFT_PACKAGE_OUTPUT/Scripts/flutter_integration.sh prebuild
       ```

    <DashImage image="development/add-to-app/ios/project-setup-swiftpm/pre-action.png" caption="Pre-action Run Script in scheme editor." />

 1. <h3>Add new run script build phase to your target</h3>

    <h3>向 target 添加新的 Run Script 构建阶段</h3>

    1. Navigate to your target's **Build Phases**
       &gt; **+** &gt; **New Run Script Phase**

       进入 target 的 **Build Phases** 
       &gt; **+** &gt; **New Run Script Phase**

    1. Set the script to the following:

       将脚本设置为：

       ```
       /bin/sh $FLUTTER_SWIFT_PACKAGE_OUTPUT/Scripts/flutter_integration.sh assemble
       ```

    1. Uncheck **Based on dependency analysis**

       取消勾选 **Based on dependency analysis**

    1. Add the following to **Input File Lists**:

       在 **Input File Lists** 中添加：

       ```
       $(FLUTTER_SWIFT_PACKAGE_OUTPUT)/Scripts/FlutterAssembleInputs.xcfilelist
       ```

    <DashImage image="development/add-to-app/ios/project-setup-swiftpm/build-phase-run-script.png" caption="New Run Script Build Phase under Build Phases." />

{:.steps}

## Next steps

## 后续步骤

You can now [add a Flutter screen][] to your existing macOS app.

你现在可以 [向现有 macOS 应用添加 Flutter 屏幕][add a Flutter screen]。

[add a Flutter screen]: /add-to-app/macos/add-flutter-screen
[build modes]: /testing/build-modes