# 将 Flutter 模块集成到 iOS 项目（旧版）

> 了解如何将 Flutter 模块集成到你现有的 iOS 项目中。



:::warning

As of Flutter 3.44, Swift Package Manager (SwiftPM) replaces CocoaPods
as the default dependency manager for iOS and macOS Flutter apps.
CocoaPods is officially in maintenance mode,
and its registry will permanently [become read-only on December 2, 2026][read-only].

自 Flutter 3.44 起，Swift Package Manager（SwiftPM）取代 CocoaPods，
成为 iOS 与 macOS Flutter 应用的默认依赖管理器。
CocoaPods 已正式进入维护模式，
其 registry 将于 2026 年 12 月 2 日永久 [变为只读][read-only]。

This guide is preserved for reference only, and will not receive ongoing maintenance.
Please migrate to using Swift Package Manager using the [updated integration guide][].

本指南仅作参考保留，不会持续维护。请使用 [更新的集成指南][updated integration guide] 迁移到 Swift Package Manager。

:::

Flutter UI components can be incrementally added into your existing iOS
application as embedded frameworks.
To embed Flutter in your existing application,
consider one of the following three methods.

可将 Flutter UI 组件以嵌入 framework 的方式逐步添加到你现有的 iOS 应用中。要将 Flutter 嵌入现有应用，可考虑以下三种方法之一。

| <t>Embedding Method</t><t>嵌入方式</t> | <t>Methodology</t><t>方法</t> | <t>Benefit</t><t>优势</t> |
|---|---|---|
| Use CocoaPods _(Recommended)_ | Install and use the Flutter SDK and CocoaPods. Flutter compiles the `flutter_module` from source each time Xcode builds the iOS app. | Least complicated method to embed Flutter into your app. |
| 使用 CocoaPods **（推荐）** | 安装并使用 Flutter SDK 与 CocoaPods。每次 Xcode 构建 iOS 应用时，Flutter 从源码编译 `flutter_module`。 | 将 Flutter 嵌入应用的最简单方式。 |
| Use [iOS frameworks][] | Create iOS frameworks for Flutter components, embed them into your iOS, and update your existing app's build settings. | Doesn't require every developer to install the Flutter SDK and CocoaPods on their local machines. |
| 使用 [iOS frameworks][] | 为 Flutter 组件创建 iOS framework，嵌入 iOS 应用，并更新现有应用的构建设置。 | 不要求每位开发者在本地安装 Flutter SDK 与 CocoaPods。 |
| Use iOS frameworks and CocoaPods | Embed the frameworks for your iOS app and the plugins in Xcode, but distribute the Flutter engine as a CocoaPods podspec. | Provides an alternative to distributing the large Flutter engine (`Flutter.xcframework`) library. |
| 使用 iOS frameworks 与 CocoaPods | 在 Xcode 中嵌入 iOS 应用与插件的 frameworks，但以 CocoaPods podspec 分发 Flutter 引擎。 | 为分发大型 Flutter 引擎（`Flutter.xcframework`）库提供替代方案。 |

{:.table .table-striped}

[iOS frameworks]: https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WhatAreFrameworks.html

When you add Flutter to your existing iOS app,
it [increases the size of your iOS app][app-size].

将 Flutter 添加到现有 iOS 应用时，会 [增大 iOS 应用体积][app-size]。

For examples using an app built with UIKit,
see the iOS directories in the [add_to_app code samples][].
For an example using SwiftUI, consult the iOS directory in [News Feed App][].

使用 UIKit 构建的应用示例，
请参阅 [add_to_app 代码示例][add_to_app code samples] 中的 iOS 目录。
SwiftUI 示例请参阅 [News Feed App][] 中的 iOS 目录。

## Development system requirements

## 开发系统要求

Flutter requires the latest version of Xcode and [CocoaPods][].

Flutter 需要最新版本的 Xcode 与 [CocoaPods][]。

## Create a Flutter module

## 创建 Flutter 模块

To embed Flutter into your existing application with any method,
create a Flutter module first.
Use the following command to create a Flutter module.

使用任一方式将 Flutter 嵌入现有应用前，
须先创建 Flutter 模块。使用以下命令创建：

```console
$ cd /path/to/my_flutter
$ flutter create --template module my_flutter
```

Flutter creates module project under `/path/to/my_flutter/`.
If you use the [CocoaPods method][], save the module
in the same parent directory as your existing iOS app.

Flutter 会在 `/path/to/my_flutter/` 下创建模块项目。
若使用 [CocoaPods 方式][CocoaPods method]，
请将模块保存在与现有 iOS 应用相同的父目录中。

[CocoaPods method]: /add-to-app/ios/project-setup-legacy/?tab=embed-using-cocoapods

From the Flutter module directory,
you can run the same `flutter` commands you would in any other Flutter project,
like `flutter run` or `flutter build ios`.
You can also run the module in [VS Code][] or
[Android Studio/IntelliJ][] with the Flutter and Dart plugins.
This project contains a single-view example version of your module
before embedding it in your existing iOS app.
This helps when testing the Flutter-only parts of your code.

在 Flutter 模块目录中，
你可运行与其他 Flutter 项目相同的 `flutter` 命令，
例如 `flutter run` 或 `flutter build ios`。
你也可在安装了 Flutter 与 Dart 插件的 [VS Code][] 或 [Android Studio/IntelliJ][] 中运行模块。
该项目包含嵌入现有 iOS 应用前的单视图示例版本，便于测试代码中仅 Flutter 的部分。

## Organize your module

## 组织模块结构

The `my_flutter` module directory structure resembles a typical Flutter app.

`my_flutter` 模块目录结构类似典型 Flutter 应用。

<FileTree>

- my_flutter/
  - .ios/
    - Runner.xcworkspace
    - Flutter/
      - podhelper.rb
  - lib/
    - main.dart
  - test/
  - pubspec.yaml

</FileTree>

Your Dart code should be added to the `lib/` directory.
Your Flutter dependencies, packages, and plugins must be added to the
`pubspec.yaml` file.

Dart 代码应放在 `lib/` 目录。Flutter 依赖、package 与插件须添加到 `pubspec.yaml`。

The `.ios/` hidden subfolder contains an Xcode workspace where
you can run a standalone version of your module.
This wrapper project bootstraps your Flutter code.
It contains helper scripts to facilitate building frameworks or
embedding the module into your existing application with CocoaPods.

隐藏的 `.ios/` 子文件夹包含 Xcode workspace，可单独运行模块。
该包装项目引导 Flutter 代码，并包含辅助脚本，
便于构建 framework 或通过 CocoaPods 将模块嵌入现有应用。

:::note

* Add custom iOS code to your own existing application's
  project or to a plugin, not to the module's `.ios/`
  directory. Changes made in your module's `.ios/`
  directory don't appear in your existing iOS project
  using the module, and might be overwritten by Flutter.

  将自定义 iOS 代码添加到你现有应用的项目或插件中，
  而非模块的 `.ios/` 目录。
  在模块 `.ios/` 目录中的更改不会出现在使用该模块的现有 iOS 项目中，
  且可能被 Flutter 覆盖。

* Exclude the `.ios/` directory from source control as
  it's autogenerated.

  将 `.ios/` 目录排除在版本控制之外，因其为自动生成。

* Before building the module on a new machine,
  run `flutter pub get` in the `my_flutter` directory.
  This regenerates the `.ios/` directory before building
  the iOS project that uses the Flutter module.

  在新机器上构建模块前，
  在 `my_flutter` 目录运行 `flutter pub get`，
  以在使用 Flutter 模块的 iOS 项目构建前重新生成 `.ios/` 目录。

:::

## Embed a Flutter module in your iOS app

## 将 Flutter 模块嵌入 iOS 应用

After you have developed your Flutter module,
you can embed it using the methods described
in the table at the top of the page.

开发完 Flutter 模块后，可使用页面顶部表格中的方法进行嵌入。

You can run in **Debug** mode on a simulator or a real device,
and **Release** mode on a real device.

可在模拟器或真机上以 **Debug** 模式运行，在真机上以 **Release** 模式运行。

:::note
Learn more about [Flutter's build modes][build modes of Flutter].

了解更多关于 [Flutter 构建模式][build modes of Flutter] 的信息。

To use Flutter debugging features such as hot reload,
consult [Debugging your add-to-app module][].

要使用热重载等 Flutter 调试功能，
请参阅 [调试 add-to-app 模块][Debugging your add-to-app module]。
:::

<Tabs key="darwin-deps">
<!-- <Tab name="Use CocoaPods"> -->
<Tab name="使用 CocoaPods">

### Use CocoaPods and the Flutter SDK {:#method-a .no_toc}

### 使用 CocoaPods 与 Flutter SDK {:#method-a .no_toc}

#### Approach {:#method-a-approach}

#### 方法 {:#method-a-approach}

This first method uses CocoaPods to embed the Flutter modules.
CocoaPods manages dependencies for Swift projects,
including Flutter code and plugins.
Each time Xcode builds the app,
CocoaPods embeds the Flutter modules.

第一种方法使用 CocoaPods 嵌入 Flutter 模块。
CocoaPods 管理 Swift 项目的依赖，包括 Flutter 代码与 plugin。
每次 Xcode 构建 app 时，CocoaPods 都会嵌入 Flutter 模块。

This allows rapid iteration with the most up-to-date
version of your Flutter module without running additional
commands outside of Xcode.

这样你可以在 Xcode 之外无需运行额外命令，即可用 Flutter 模块的最新版本快速迭代。

To learn more about CocoaPods,
consult the [CocoaPods getting started guide][].

要了解更多 CocoaPods 信息，请参阅 [CocoaPods 入门指南][CocoaPods getting started guide]。

#### Watch the video

#### 观看视频

If watching a video helps you learn,
this video covers adding Flutter to an iOS app:

若观看视频有助于学习，本视频介绍如何将 Flutter 添加到 iOS app：

<YouTubeEmbed id="IIcrfrTshTs" title="Step by step on how to add Flutter to an existing iOS app"></YouTubeEmbed>

#### Requirements {:#method-a-reqs}

#### 要求 {:#method-a-reqs}

Every developer working on your project must have a local version
of the Flutter SDK and CocoaPods installed.

参与项目的每位开发者都必须在本地安装 Flutter SDK 和 CocoaPods。

#### Example project structure {:#method-a-structure}

#### 示例项目结构 {:#method-a-structure}

This section assumes that your existing app and
the Flutter module reside in sibling directories.
If you have a different directory structure,
adjust the relative paths.
The example directory structure resembles the following:

本节假定现有 app 与 Flutter 模块位于同级目录。
若目录结构不同，请调整相对路径。
示例目录结构如下：

<FileTree>

- my_flutter/
   - .ios/
   - Flutter/
      - podhelper.rb
- MyApp/
   - Podfile

</FileTree>

#### Update your Podfile

#### 更新你的 Podfile

Add your Flutter modules to your Podfile configuration file.
This section presumes you called your Swift app `MyApp`.

将 Flutter 模块添加到你的 Podfile 配置文件。
本节假定你的 Swift app 名为 `MyApp`。

1. _(Optional)_ If your existing app lacks a `Podfile` config file,
   navigate to the root of your app directory.
   Use the `pod init` command to create the `Podfile` file.

   **（可选）** 若现有 app 没有 `Podfile` 配置文件，请进入 app 目录根目录，使用 `pod init` 命令创建 `Podfile` 文件。

   :::tip
   If the `pod init` command errors,
   check that you're on the latest version of CocoaPods.

   若 `pod init` 命令报错，请确认你使用的是最新版 CocoaPods。
   :::

1. Update your `Podfile` config file.

   更新你的 `Podfile` 配置文件。

   1. Add the following lines after the `platform` declaration.

      在 `platform` 声明之后添加以下行。

      ```ruby title="MyApp/Podfile"
      flutter_application_path = '../my_flutter'
      load File.join(flutter_application_path, '.ios', 'Flutter', 'podhelper.rb')
      ```

   1. For each [Podfile target][] that needs to embed Flutter,
      add a call to the
      `install_all_flutter_pods(flutter_application_path)` method.
      Add these calls after the settings in the previous step.

      对于每个需要嵌入 Flutter 的 [Podfile target][Podfile target]，添加对 `install_all_flutter_pods(flutter_application_path)` 方法的调用。在上一步设置之后添加这些调用。

      ```ruby title="MyApp/Podfile"
      target 'MyApp' do
        install_all_flutter_pods(flutter_application_path)
      end
      ```

   1. In the `Podfile`'s `post_install` block,
      add a call to `flutter_post_install(installer)`.
      This block should be the last block in the `Podfile` config file.

      在 `Podfile` 的 `post_install` 块中，添加对 `flutter_post_install(installer)` 的调用。该块应是 `Podfile` 配置文件中的最后一个块。

      ```ruby title="MyApp/Podfile"
      post_install do |installer|
        flutter_post_install(installer) if defined?(flutter_post_install)
      end
      ```

To review an example `Podfile`, consult this [Flutter Podfile sample][].

要查看 `Podfile` 示例，请参阅此 [Flutter Podfile 示例][Flutter Podfile sample]。

#### Embed your frameworks

#### 嵌入你的 framework

At build time, Xcode packages your Dart code, each Flutter plugin,
and the Flutter engine into their own `*.xcframework` bundles.
CocoaPod's `podhelper.rb` script then embeds these
`*.xcframework` bundles into your project.

构建时，Xcode 会将 Dart 代码、每个 Flutter plugin 以及 Flutter engine 分别打包为各自的 `*.xcframework` bundle。
随后 CocoaPods 的 `podhelper.rb` 脚本将这些 `*.xcframework` bundle 嵌入你的项目。

* `Flutter.xcframework` contains the Flutter engine.

  `Flutter.xcframework` 包含 Flutter engine。

* `App.xcframework` contains the compiled Dart code for this project.

  `App.xcframework` 包含本项目的已编译 Dart 代码。

* `<plugin>.xcframework` contains one Flutter plugin.

  `<plugin>.xcframework` 包含一个 Flutter plugin。

To embed the Flutter engine, your Dart code, and your Flutter plugins
into your iOS app, complete the following procedure.

要将 Flutter engine、Dart 代码和 Flutter plugin 嵌入 iOS app，请完成以下步骤。

1. Refresh your Flutter plugins.

   刷新 Flutter plugin。

   If you change the Flutter dependencies in the `pubspec.yaml` file,
   run `flutter pub get` in your Flutter module directory.
   This refreshes the list of plugins that the `podhelper.rb` script reads.

   若更改了 `pubspec.yaml` 中的 Flutter 依赖，请在 Flutter 模块目录中运行 `flutter pub get`。
   这会刷新 `podhelper.rb` 脚本读取的 plugin 列表。

   ```console
   flutter pub get
   ```

1. Embed the plugins and frameworks with CocoaPods.

   使用 CocoaPods 嵌入 plugin 与 framework。

   1. Navigate to your iOS app project at `/path/to/MyApp/MyApp`.

      进入 iOS app 项目目录 `/path/to/MyApp/MyApp`。

   1. Use the `pod install` command.

      使用 `pod install` 命令。

      ```console
      pod install
      ```

   Your iOS app's **Debug** and **Release** build configurations embed
   the corresponding [Flutter components for that build mode][build-modes].

   iOS app 的 **Debug** 与 **Release** 构建配置会嵌入对应[该构建模式的 Flutter 组件][build-modes]。

1. Build the project.

   构建项目。

   1. Open `MyApp.xcworkspace` in Xcode.

      在 Xcode 中打开 `MyApp.xcworkspace`。

      Verify that you're opening `MyApp.xcworkspace` and
      not opening `MyApp.xcodeproj`.
      The `.xcworkspace` file has the CocoaPod dependencies,
      the `.xcodeproj` doesn't.

      请确认打开的是 `MyApp.xcworkspace`，而不是 `MyApp.xcodeproj`。
      `.xcworkspace` 文件包含 CocoaPods 依赖，`.xcodeproj` 则没有。

   1. Select **Product** > **Build** or press <kbd>Cmd</kbd> + <kbd>B</kbd>.

      选择 **Product** > **Build**，或按 <kbd>Cmd</kbd> + <kbd>B</kbd>。

#### Set LLDB Init File

#### 设置 LLDB Init File

:::warning
Set your scheme to use Flutter's LLDB Init File. Without this file, debugging
on an iOS 26 or later device may crash.

请将 scheme 设置为使用 Flutter 的 LLDB Init File。没有此文件时，在 iOS 26 及更高版本设备上调试可能会崩溃。
:::

1. Generate Flutter LLDB files.

   生成 Flutter LLDB 文件。

   1. Within your flutter application, run the following:

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

   ```console
   flutter build ios --config-only
   ```

   This will generate the LLDB files in the `.ios/Flutter/ephemeral` directory.

   这会在 `.ios/Flutter/ephemeral` 目录中生成 LLDB 文件。

1. Set the LLDB Init File.

   设置 LLDB Init File。

   1. Go to **Product > Scheme > Edit Scheme**.

      前往 **Product > Scheme > Edit Scheme**。

   1. Select the **Run** section in the left side bar.

      在左侧边栏选择 **Run** 部分。

   1. Set the **LLDB Init File** using the same relative path to your Flutter
      application as you put in your Podfile in the **Update your Podfile**
      section.

      设置 **LLDB Init File**，使用与 **Update your Podfile**（更新你的 Podfile）一节中 Podfile 相同的、指向 Flutter 应用的相对路径。

      ```console
      $(SRCROOT)/../my_flutter/.ios/Flutter/ephemeral/flutter_lldbinit
      ```

      If your scheme already has an **LLDB Init File**, you can add Flutter's
      LLDB file to it. The path to Flutter's LLDB Init File must be relative
      to the location of your project's LLDB Init File.

      若 scheme 已有 **LLDB Init File**，可将 Flutter 的 LLDB 文件加入其中。Flutter LLDB Init File 的路径必须相对于项目 LLDB Init File 的位置。

      For example, if your LLDB file is located at `/path/to/MyApp/.lldbinit`,
      you would add the following:

      例如，若 LLDB 文件位于 `/path/to/MyApp/.lldbinit`，可添加以下内容：

      ```console
      command source --relative-to-command-file "../my_flutter/.ios/Flutter/ephemeral/flutter_lldbinit"
      ```

[build-modes]: /testing/build-modes
[CocoaPods getting started guide]: https://guides.cocoapods.org/using/using-cocoapods.html
[Podfile target]: https://guides.cocoapods.org/syntax/podfile.html#target
[Flutter Podfile sample]: https://github.com/flutter/samples/blob/main/add_to_app/plugin/ios_using_plugin/Podfile


</Tab>
<!-- <Tab name="Use frameworks"> -->
<Tab name="使用 frameworks">

### Link and Embed frameworks in Xcode {:#method-b .no_toc}

### 在 Xcode 中链接并嵌入 framework {:#method-b .no_toc}

#### Approach {:#method-b-approach}

#### 方法 {:#method-b-approach}

In this second method, edit your existing Xcode project,
generate the necessary frameworks, and embed them in your app.
Flutter generates iOS frameworks for Flutter itself,
for your compiled Dart code, and for each of your Flutter plugins.
Embed these frameworks and update your existing application's build settings.

在第二种方法中，编辑你现有的 Xcode 项目，生成所需的 framework，并将其嵌入 app。
Flutter 会为 Flutter 自身、你已编译的 Dart 代码以及每个 Flutter plugin 生成 iOS framework。
嵌入这些 framework 并更新现有应用的构建设置。

#### Requirements {:#method-b-reqs}

#### 要求 {:#method-b-reqs}

No additional software or hardware requirements are needed for this method.
Use this method in the following use cases:

此方法不需要额外的软件或硬件。
在以下用例中使用此方法：

* Members of your team can't install the Flutter SDK and CocoaPods

  团队成员无法安装 Flutter SDK 和 CocoaPods

* You don't want to use CocoaPods as a dependency manager in existing iOS apps

  你不想在现有 iOS app 中使用 CocoaPods 作为依赖管理器

#### Limitations {:#method-b-limits}

#### 限制 {:#method-b-limits}


Flutter can't handle [common dependencies with xcframeworks][common].
If both the host app and the Flutter module's plugin define the
same pod dependency and you integrate Flutter module using this option,
errors result.
These errors include issues like `Multiple commands produce
'CommonDependency.framework'`.

Flutter 无法处理[与 xcframework 的公共依赖][common]。
如果宿主 app 与 Flutter 模块的 plugin 都定义了相同的 pod 依赖，而你又通过此选项集成 Flutter 模块，就会产生错误。
这些错误包括诸如 `Multiple commands produce
'CommonDependency.framework'` 之类的问题。

To work around this issue, link every plugin source in its `podspec` file
from the Flutter module to the host app's `Podfile`.
Link the source instead of the plugins' `xcframework` framework.
The next section explains how to [produce that framework][ios-framework].

要解决此问题，请将 Flutter 模块中每个 plugin 在其 `podspec` 文件里的源码链接到宿主 app 的 `Podfile`。
应链接源码，而不是 plugin 的 `xcframework` framework。
下一节说明如何[生成该 framework][ios-framework]。

To prevent the error that occurs when common dependencies exist,
use `flutter build ios-framework` with the `--no-plugins` flag.

为防止出现公共依赖导致的错误，请使用带 `--no-plugins` 标志的 `flutter build ios-framework`。

[common]: https://github.com/flutter/flutter/issues/130220
[ios-framework]: https://github.com/flutter/flutter/issues/114692


#### Example project structure {:#method-b-structure}

#### 示例项目结构 {:#method-b-structure}

The following example assumes that you want to generate the
frameworks to `/path/to/MyApp/Flutter/`.

以下示例假定你要将 framework 生成到 `/path/to/MyApp/Flutter/`。

```console
$ flutter build ios-framework --output=/path/to/MyApp/Flutter/
```

Run this _every time_ you change code in your Flutter module.

**每次** 更改 Flutter 模块中的代码时都要运行此命令。

The resulting project structure should resemble this directory tree.

生成的项目结构应与此目录树类似。

<FileTree>

- /path/to/MyApp/
  - Flutter/
    - Debug/
      - Flutter.xcframework
      - App.xcframework
      - FlutterPluginRegistrant.xcframework (If you have plugins with iOS-platform code)
      - example_plugin.xcframework (One framework file for each plugin)
    - Profile/
      - Flutter.xcframework
      - App.xcframework
      - FlutterPluginRegistrant.xcframework
      - example_plugin.xcframework
    - Release/
      - Flutter.xcframework
      - App.xcframework
      - FlutterPluginRegistrant.xcframework
      - example_plugin.xcframework

</FileTree>

:::warning
Always use `Flutter.xcframework` and `App.xcframework` bundles
located in the same directory.
Mixing `.xcframework` imports from different directories
(like `Profile/Flutter.xcframework` with `Debug/App.xcframework`)
causes runtime crashes.

始终使用位于同一目录中的 `Flutter.xcframework` 和 `App.xcframework` bundle。
混用来自不同目录的 `.xcframework` 导入
（例如将 `Profile/Flutter.xcframework` 与 `Debug/App.xcframework` 搭配使用）
会导致运行时崩溃。
:::


#### Procedures

#### 步骤

How you link, embed, or both the generated frameworks
into your existing app in Xcode depends on the type of framework.

在 Xcode 中将生成的 framework 链接、嵌入或同时执行两者，取决于 framework 的类型。

* Link and embed dynamic frameworks.

  链接并嵌入动态 framework。

* Link static frameworks. [Never embed them][static-framework].

  链接静态 framework。[切勿嵌入它们][static-framework]。

Flutter plugins might produce [static or dynamic frameworks][].
Link static frameworks, [_never_ embed them][static-framework].

Flutter plugin 可能生成 [静态或动态 framework][static or dynamic frameworks]。
请链接静态 framework，[**切勿** 嵌入它们][static-framework]。

If you embed a static framework into your iOS app,
you can't publish that app to the App Store.
Publishing fails with a
`Found an unexpected Mach-O header code` archive error.

若将静态 framework 嵌入 iOS app，则无法将该 app 发布到 App Store。
发布时会因 `Found an unexpected Mach-O header code` 归档错误而失败。

##### Link all frameworks

##### 链接所有 framework

To link the necessary frameworks, follow this procedure.

要链接所需 framework，请按以下步骤操作。

1. Choose the frameworks to link.

   选择要链接的 framework。

   1. In the **Project Navigator**, click on your project.

      在 **Project Navigator** 中点击你的项目。

   1. Click the **Build Phases** tab.

      点击 **Build Phases** 标签页。

   1. Expand **Link Binary With Libraries**.

      展开 **Link Binary With Libraries**。

      <DashImage image="development/add-to-app/ios/project-setup/linked-libraries.png" caption="Expand the **Link Binary With Libraries** build phase in Xcode" />

   1. Click **+** (plus sign).

      点击 **+**（加号）。

   1. Click **Add Other...** then **Add Files...**.

      点击 **Add Other...**，然后点击 **Add Files...**。

   1. From the **Choose frameworks and libraries to add:** dialog box,
      navigate to the `/path/to/MyApp/Flutter/Release/` directory.

      在 **Choose frameworks and libraries to add:** 对话框中，导航到 `/path/to/MyApp/Flutter/Release/` 目录。

   1. Command-click the frameworks in that directory then click **Open**.

      按住 Command 键点击该目录中的 framework，然后点击 **Open**。

      <DashImage image="development/add-to-app/ios/project-setup/choose-libraries.png" caption="Choose frameworks to link from the **Choose frameworks and libraries to add:** dialog box in Xcode" />

1. Update the paths to the libraries to account for build modes.

   更新库路径以适配构建模式。

   1. Launch the Finder.

      打开 Finder。

   1. Navigate to the `/path/to/MyApp/` directory.

      导航到 `/path/to/MyApp/` 目录。

   1. Right-click on `MyApp.xcodeproj` and select **Show Package
      Contents**.

      右键点击 `MyApp.xcodeproj`，选择 **Show Package Contents**。

   1. Open `project.pbxproj` with Xcode. The file opens in Xcode's text
      editor. This also locks **Project Navigator** until you close the text editor.

      用 Xcode 打开 `project.pbxproj`。文件会在 Xcode 文本编辑器中打开。在关闭文本编辑器之前，**Project Navigator** 也会被锁定。

      <DashImage image="development/add-to-app/ios/project-setup/project-pbxproj.png" caption="The `project-pbxproj` file open in the Xcode text editor" />

   1. Find the lines that resemble the following text in the
      `/* Begin PBXFileReference section */`.

      在 `/* Begin PBXFileReference section */` 中查找类似以下内容的行。

      ```text
      312885572C1A441C009F74FF /* Flutter.xcframework */ = {
        isa = PBXFileReference;
        expectedSignature = "AppleDeveloperProgram:S8QB4VV633:FLUTTER.IO LLC";
        lastKnownFileType = wrapper.xcframework;
        name = Flutter.xcframework;
        path = Flutter/[!Release!]/Flutter.xcframework;
        sourceTree = "<group>";
      };
      312885582C1A441C009F74FF /* App.xcframework */ = {
        isa = PBXFileReference;
        lastKnownFileType = wrapper.xcframework;
        name = App.xcframework;
        path = Flutter/[!Release!]/App.xcframework;
        sourceTree = "<group>";
      };
      ```

   1. Change the `Release` text highlighted in the prior step
      and change it to `$(CONFIGURATION)`. Also wrap the path in
      quotation marks.

      将上一步中高亮的 `Release` 文本改为 `$(CONFIGURATION)`，并用引号包裹路径。

      ```text
      312885572C1A441C009F74FF /* Flutter.xcframework */ = {
        isa = PBXFileReference;
        expectedSignature = "AppleDeveloperProgram:S8QB4VV633:FLUTTER.IO LLC";
        lastKnownFileType = wrapper.xcframework;
        name = Flutter.xcframework;
        path = [!"!]Flutter/[!$(CONFIGURATION)!]/Flutter.xcframework[!"!];
        sourceTree = "<group>";
      };
      312885582C1A441C009F74FF /* App.xcframework */ = {
        isa = PBXFileReference;
        lastKnownFileType = wrapper.xcframework;
        name = App.xcframework;
        path = [!"!]Flutter/[!$(CONFIGURATION)!]/App.xcframework[!"!];
        sourceTree = "<group>";
      };
      ```

1. Update the search paths.

   更新搜索路径。

   1. Click the **Build Settings** tab.

      点击 **Build Settings** 标签页。

   1. Navigate to **Search Paths**

      导航到 **Search Paths**

   1. Double-click to the right of **Framework Search Paths**.

      双击 **Framework Search Paths** 右侧。

   1. In the combo box, click **+** (plus sign).

      在组合框中点击 **+**（加号）。

   1. Type `$(inherited)`.
      and press <kbd>Enter</kbd>.

      输入 `$(inherited)`，然后按 <kbd>Enter</kbd>。

   1. Click **+** (plus sign).

      点击 **+**（加号）。

   1. Type `$(PROJECT_DIR)/Flutter/$(CONFIGURATION)/`
      and press <kbd>Enter</kbd>.

      输入 `$(PROJECT_DIR)/Flutter/$(CONFIGURATION)/`，然后按 <kbd>Enter</kbd>。

      <DashImage image="development/add-to-app/ios/project-setup/framework-search-paths.png" caption="Update **Framework Search Paths** in Xcode" />

After linking the frameworks, they should display in the
**Frameworks, Libraries, and Embedded Content**
section of your target's **General** settings.

链接 framework 后，它们应显示在 target **General** 设置的 **Frameworks, Libraries, and Embedded Content** 部分。

##### Embed the dynamic frameworks

##### 嵌入动态 framework

To embed your dynamic frameworks, complete the following procedure.

要嵌入动态 framework，请完成以下步骤。

1. Navigate to **General** <span aria-label="and then">></span>
   **Frameworks, Libraries, and Embedded Content**.

   导航到 **General** <span aria-label="and then">></span> **Frameworks, Libraries, and Embedded Content**。

1. Click on each of your dynamic frameworks and select **Embed & Sign**.

   点击每个动态 framework，选择 **Embed & Sign**。

   <DashImage image="development/add-to-app/ios/project-setup/choose-to-embed.png" caption="Select **Embed & Sign** for each of your frameworks in Xcode" />

   Don't include any static frameworks,
   including `FlutterPluginRegistrant.xcframework`.

   不要包含任何静态 framework，包括 `FlutterPluginRegistrant.xcframework`。

1. Click the **Build Phases** tab.

   点击 **Build Phases** 标签页。

1. Expand **Embed Frameworks**.
   Your dynamic frameworks should display in that section.

   展开 **Embed Frameworks**。动态 framework 应显示在该部分。

   <DashImage image="development/add-to-app/ios/project-setup/embed-xcode.png" caption="The expanded **Embed Frameworks** build phase in Xcode" />

1. Build the project.

   构建项目。

   1. Open `MyApp.xcworkspace` in Xcode.

      在 Xcode 中打开 `MyApp.xcworkspace`。

      Verify that you're opening `MyApp.xcworkspace` and
      not opening `MyApp.xcodeproj`.
      The `.xcworkspace` file has the CocoaPod dependencies,
      the `.xcodeproj` doesn't.

      请确认打开的是 `MyApp.xcworkspace`，而不是 `MyApp.xcodeproj`。
      `.xcworkspace` 文件包含 CocoaPods 依赖，`.xcodeproj` 则没有。

   1. Select **Product** <span aria-label="and then">></span>
      **Build** or press <kbd>Cmd</kbd> + <kbd>B</kbd>.

      选择 **Product** <span aria-label="and then">></span> **Build**，或按 <kbd>Cmd</kbd> + <kbd>B</kbd>。

#### Set LLDB Init File

#### 设置 LLDB Init File

:::warning
Set your scheme to use Flutter's LLDB Init File. Without this file, debugging
on an iOS 26 or later device may crash.

请将 scheme 设置为使用 Flutter 的 LLDB Init File。没有此文件时，在 iOS 26 及更高版本设备上调试可能会崩溃。
:::

1. Generate Flutter LLDB files.

   生成 Flutter LLDB 文件。

   1. Within your flutter application, re-run `flutter build ios-framework` if
      you haven't already:

      在 Flutter 应用中，若尚未运行，请重新执行 `flutter build ios-framework`：

   ```console
   $ flutter build ios-framework --output=/path/to/MyApp/Flutter/
   ```

   This will generate the LLDB files in the `/path/to/MyApp/Flutter/` directory.

   这会在 `/path/to/MyApp/Flutter/` 目录中生成 LLDB 文件。

1. Set the LLDB Init File.

   设置 LLDB Init File。

   1. Go to **Product > Scheme > Edit Scheme**.

      前往 **Product > Scheme > Edit Scheme**。

   1. Select the **Run** section in the left side bar.

      在左侧边栏选择 **Run** 部分。

   1. Set the **LLDB Init File** to the following:

      将 **LLDB Init File** 设置为以下内容：

      ```console
      $(PROJECT_DIR)/Flutter/flutter_lldbinit
      ```

      If your scheme already has an **LLDB Init File**, you can add Flutter's
      LLDB file to it. The path to Flutter's LLDB Init File must be relative
      to the location of your project's LLDB Init File.

      若 scheme 已有 **LLDB Init File**，可将 Flutter 的 LLDB 文件加入其中。Flutter LLDB Init File 的路径必须相对于项目 LLDB Init File 的位置。

      For example, if your LLDB file is located at `/path/to/MyApp/.lldbinit`,
      you would add the following:

      例如，若 LLDB 文件位于 `/path/to/MyApp/.lldbinit`，可添加以下内容：

      ```console
      command source --relative-to-command-file "Flutter/flutter_lldbinit"
      ```

[static or dynamic frameworks]: https://stackoverflow.com/questions/32591878/ios-is-it-a-static-or-a-dynamic-framework
[static-framework]: https://developer.apple.com/library/archive/technotes/tn2435/_index.html


[static-framework]: https://developer.apple.com/library/archive/technotes/tn2435/_index.html


</Tab>
<!-- <Tab name="Use frameworks and CocoaPods"> -->
<Tab name="使用 frameworks 和 CocoaPods">

### Use frameworks in Xcode and Flutter framework as podspec {:#method-c .no_toc}

### 在 Xcode 中使用 framework，并将 Flutter framework 作为 podspec {:#method-c .no_toc}

#### Approach {:#method-c-approach}

#### 方法 {:#method-c-approach}

This method generates Flutter as a CocoaPods podspec instead of
distributing the large `Flutter.xcframework` to other developers,
machines, or continuous integration systems.
Flutter still generates iOS frameworks for your compiled Dart code,
and for each of your Flutter plugins.
Embed these frameworks and update your existing application's build settings.

此方法将 Flutter 生成为 CocoaPods podspec，而不是将大型 `Flutter.xcframework` 分发给其他开发者、机器或持续集成系统。
Flutter 仍会为已编译的 Dart 代码以及每个 Flutter plugin 生成 iOS framework。
嵌入这些 framework 并更新现有应用的构建设置。

#### Requirements {:#method-c-reqs}

#### 要求 {:#method-c-reqs}

No additional software or hardware requirements are needed for this method.
Use this method in the following use cases:

此方法不需要额外的软件或硬件。
在以下用例中使用此方法：

* Members of your team can't install the Flutter SDK and CocoaPods

  团队成员无法安装 Flutter SDK 和 CocoaPods

* You don't want to use CocoaPods as a dependency manager in existing iOS apps

  你不想在现有 iOS app 中使用 CocoaPods 作为依赖管理器

#### Limitations {:#method-c-limits}

#### 限制 {:#method-c-limits}


Flutter can't handle [common dependencies with xcframeworks][common].
If both the host app and the Flutter module's plugin define the
same pod dependency and you integrate Flutter module using this option,
errors result.
These errors include issues like `Multiple commands produce
'CommonDependency.framework'`.

Flutter 无法处理[与 xcframework 的公共依赖][common]。
如果宿主 app 与 Flutter 模块的 plugin 都定义了相同的 pod 依赖，而你又通过此选项集成 Flutter 模块，就会产生错误。
这些错误包括诸如 `Multiple commands produce
'CommonDependency.framework'` 之类的问题。

To work around this issue, link every plugin source in its `podspec` file
from the Flutter module to the host app's `Podfile`.
Link the source instead of the plugins' `xcframework` framework.
The next section explains how to [produce that framework][ios-framework].

要解决此问题，请将 Flutter 模块中每个 plugin 在其 `podspec` 文件里的源码链接到宿主 app 的 `Podfile`。
应链接源码，而不是 plugin 的 `xcframework` framework。
下一节说明如何[生成该 framework][ios-framework]。

To prevent the error that occurs when common dependencies exist,
use `flutter build ios-framework` with the `--no-plugins` flag.

为防止出现公共依赖导致的错误，请使用带 `--no-plugins` 标志的 `flutter build ios-framework`。

[common]: https://github.com/flutter/flutter/issues/130220
[ios-framework]: https://github.com/flutter/flutter/issues/114692


This method only works with the `beta` or `stable` [release channels][].

此方法仅适用于 `beta` 或 `stable` [发布渠道][release channels]。

[release channels]: /install/upgrade#switching-flutter-channels

#### Example project structure {:#method-c-structure}

#### 示例项目结构 {:#method-c-structure}

The following example assumes that you want to generate the
frameworks to `/path/to/MyApp/Flutter/`.

以下示例假定你要将 framework 生成到 `/path/to/MyApp/Flutter/`。

```console
$ flutter build ios-framework --output=/path/to/MyApp/Flutter/
```

Run this _every time_ you change code in your Flutter module.

**每次** 更改 Flutter 模块中的代码时都要运行此命令。

The resulting project structure should resemble this directory tree.

生成的项目结构应与此目录树类似。

<FileTree>

- /path/to/MyApp/
  - Flutter/
    - Debug/
      - Flutter.xcframework
      - App.xcframework
      - FlutterPluginRegistrant.xcframework (If you have plugins with iOS-platform code)
      - example_plugin.xcframework (One framework file for each plugin)
    - Profile/
      - Flutter.xcframework
      - App.xcframework
      - FlutterPluginRegistrant.xcframework
      - example_plugin.xcframework
    - Release/
      - Flutter.xcframework
      - App.xcframework
      - FlutterPluginRegistrant.xcframework
      - example_plugin.xcframework

</FileTree>

:::warning
Always use `Flutter.xcframework` and `App.xcframework` bundles
located in the same directory.
Mixing `.xcframework` imports from different directories
(like `Profile/Flutter.xcframework` with `Debug/App.xcframework`)
causes runtime crashes.

始终使用位于同一目录中的 `Flutter.xcframework` 和 `App.xcframework` bundle。
混用来自不同目录的 `.xcframework` 导入
（例如将 `Profile/Flutter.xcframework` 与 `Debug/App.xcframework` 搭配使用）
会导致运行时崩溃。
:::


#### Add Flutter engine to your Podfile

#### 将 Flutter engine 添加到你的 Podfile

Host apps using CocoaPods can add the Flutter engine to their Podfile.

使用 CocoaPods 的宿主 app 可以将 Flutter engine 添加到其 Podfile。

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

:::note
You must hard code the `[build mode]` value.
For example, use `Debug` if you need to use `flutter attach`
and `Release` when you're ready to ship.

你必须硬编码 `[build mode]` 值。
例如，若需要使用 `flutter attach` 请使用 `Debug`，准备发布时使用 `Release`。
:::

#### Link and embed app and plugin frameworks

#### 链接并嵌入 app 与 plugin framework

Flutter plugins might produce [static or dynamic frameworks][].
Link static frameworks, [_never_ embed them][static-framework].

Flutter plugin 可能生成 [静态或动态 framework][static or dynamic frameworks]。
请链接静态 framework，[**切勿** 嵌入它们][static-framework]。

If you embed a static framework into your iOS app,
you can't publish that app to the App Store.
Publishing fails with a
`Found an unexpected Mach-O header code` archive error.

若将静态 framework 嵌入 iOS app，则无法将该 app 发布到 App Store。
发布时会因 `Found an unexpected Mach-O header code` 归档错误而失败。

##### Link all frameworks

##### 链接所有 framework

To link the necessary frameworks, follow this procedure.

要链接所需 framework，请按以下步骤操作。

1. Choose the frameworks to link.

   选择要链接的 framework。

   1. In the **Project Navigator**, click on your project.

      在 **Project Navigator** 中点击你的项目。

   1. Click the **Build Phases** tab.

      点击 **Build Phases** 标签页。

   1. Expand **Link Binary With Libraries**.

      展开 **Link Binary With Libraries**。

      <DashImage image="development/add-to-app/ios/project-setup/linked-libraries.png" caption="Expand the **Link Binary With Libraries** build phase in Xcode" />

   1. Click **+** (plus sign).

      点击 **+**（加号）。

   1. Click **Add Other...** then **Add Files...**.

      点击 **Add Other...**，然后点击 **Add Files...**。

   1. From the **Choose frameworks and libraries to add:** dialog box,
      navigate to the `/path/to/MyApp/Flutter/Release/` directory.

      在 **Choose frameworks and libraries to add:** 对话框中，导航到 `/path/to/MyApp/Flutter/Release/` 目录。

   1. Command-click the frameworks in that directory then click **Open**.

      按住 Command 键点击该目录中的 framework，然后点击 **Open**。

      <DashImage image="development/add-to-app/ios/project-setup/choose-libraries.png" caption="Choose frameworks to link from the **Choose frameworks and libraries to add:** dialog box in Xcode" />

1. Update the paths to the libraries to account for build modes.

   更新库路径以适配构建模式。

   1. Launch the Finder.

      打开 Finder。

   1. Navigate to the `/path/to/MyApp/` directory.

      导航到 `/path/to/MyApp/` 目录。

   1. Right-click on `MyApp.xcodeproj` and select **Show Package
      Contents**.

      右键点击 `MyApp.xcodeproj`，选择 **Show Package Contents**。

   1. Open `project.pbxproj` with Xcode. The file opens in Xcode's text
      editor. This also locks **Project Navigator** until you close the text editor.

      用 Xcode 打开 `project.pbxproj`。文件会在 Xcode 文本编辑器中打开。在关闭文本编辑器之前，**Project Navigator** 也会被锁定。

      <DashImage image="development/add-to-app/ios/project-setup/project-pbxproj.png" caption="The `project-pbxproj` file open in the Xcode text editor" />

   1. Find the lines that resemble the following text in the
      `/* Begin PBXFileReference section */`.

      在 `/* Begin PBXFileReference section */` 中查找类似以下内容的行。

      ```text
      312885572C1A441C009F74FF /* Flutter.xcframework */ = {
        isa = PBXFileReference;
        expectedSignature = "AppleDeveloperProgram:S8QB4VV633:FLUTTER.IO LLC";
        lastKnownFileType = wrapper.xcframework;
        name = Flutter.xcframework;
        path = Flutter/[!Release!]/Flutter.xcframework;
        sourceTree = "<group>";
      };
      312885582C1A441C009F74FF /* App.xcframework */ = {
        isa = PBXFileReference;
        lastKnownFileType = wrapper.xcframework;
        name = App.xcframework;
        path = Flutter/[!Release!]/App.xcframework;
        sourceTree = "<group>";
      };
      ```

   1. Change the `Release` text highlighted in the prior step
      and change it to `$(CONFIGURATION)`. Also wrap the path in
      quotation marks.

      将上一步中高亮的 `Release` 文本改为 `$(CONFIGURATION)`，并用引号包裹路径。

      ```text
      312885572C1A441C009F74FF /* Flutter.xcframework */ = {
        isa = PBXFileReference;
        expectedSignature = "AppleDeveloperProgram:S8QB4VV633:FLUTTER.IO LLC";
        lastKnownFileType = wrapper.xcframework;
        name = Flutter.xcframework;
        path = [!"!]Flutter/[!$(CONFIGURATION)!]/Flutter.xcframework[!"!];
        sourceTree = "<group>";
      };
      312885582C1A441C009F74FF /* App.xcframework */ = {
        isa = PBXFileReference;
        lastKnownFileType = wrapper.xcframework;
        name = App.xcframework;
        path = [!"!]Flutter/[!$(CONFIGURATION)!]/App.xcframework[!"!];
        sourceTree = "<group>";
      };
      ```

1. Update the search paths.

   更新搜索路径。

   1. Click the **Build Settings** tab.

      点击 **Build Settings** 标签页。

   1. Navigate to **Search Paths**

      导航到 **Search Paths**

   1. Double-click to the right of **Framework Search Paths**.

      双击 **Framework Search Paths** 右侧。

   1. In the combo box, click **+** (plus sign).

      在组合框中点击 **+**（加号）。

   1. Type `$(inherited)`.
      and press <kbd>Enter</kbd>.

      输入 `$(inherited)`，然后按 <kbd>Enter</kbd>。

   1. Click **+** (plus sign).

      点击 **+**（加号）。

   1. Type `$(PROJECT_DIR)/Flutter/$(CONFIGURATION)/`
      and press <kbd>Enter</kbd>.

      输入 `$(PROJECT_DIR)/Flutter/$(CONFIGURATION)/`，然后按 <kbd>Enter</kbd>。

      <DashImage image="development/add-to-app/ios/project-setup/framework-search-paths.png" caption="Update **Framework Search Paths** in Xcode" />

After linking the frameworks, they should display in the
**Frameworks, Libraries, and Embedded Content**
section of your target's **General** settings.

链接 framework 后，它们应显示在 target **General** 设置的 **Frameworks, Libraries, and Embedded Content** 部分。

##### Embed the dynamic frameworks

##### 嵌入动态 framework

To embed your dynamic frameworks, complete the following procedure.

要嵌入动态 framework，请完成以下步骤。

1. Navigate to **General** <span aria-label="and then">></span>
   **Frameworks, Libraries, and Embedded Content**.

   导航到 **General** <span aria-label="and then">></span> **Frameworks, Libraries, and Embedded Content**。

1. Click on each of your dynamic frameworks and select **Embed & Sign**.

   点击每个动态 framework，选择 **Embed & Sign**。

   <DashImage image="development/add-to-app/ios/project-setup/choose-to-embed.png" caption="Select **Embed & Sign** for each of your frameworks in Xcode" />

   Don't include any static frameworks,
   including `FlutterPluginRegistrant.xcframework`.

   不要包含任何静态 framework，包括 `FlutterPluginRegistrant.xcframework`。

1. Click the **Build Phases** tab.

   点击 **Build Phases** 标签页。

1. Expand **Embed Frameworks**.
   Your dynamic frameworks should display in that section.

   展开 **Embed Frameworks**。动态 framework 应显示在该部分。

   <DashImage image="development/add-to-app/ios/project-setup/embed-xcode.png" caption="The expanded **Embed Frameworks** build phase in Xcode" />

1. Build the project.

   构建项目。

   1. Open `MyApp.xcworkspace` in Xcode.

      在 Xcode 中打开 `MyApp.xcworkspace`。

      Verify that you're opening `MyApp.xcworkspace` and
      not opening `MyApp.xcodeproj`.
      The `.xcworkspace` file has the CocoaPod dependencies,
      the `.xcodeproj` doesn't.

      请确认打开的是 `MyApp.xcworkspace`，而不是 `MyApp.xcodeproj`。
      `.xcworkspace` 文件包含 CocoaPods 依赖，`.xcodeproj` 则没有。

   1. Select **Product** <span aria-label="and then">></span>
      **Build** or press <kbd>Cmd</kbd> + <kbd>B</kbd>.

      选择 **Product** <span aria-label="and then">></span> **Build**，或按 <kbd>Cmd</kbd> + <kbd>B</kbd>。

#### Set LLDB Init File

#### 设置 LLDB Init File

:::warning
Set your scheme to use Flutter's LLDB Init File. Without this file, debugging
on an iOS 26 or later device may crash.

请将 scheme 设置为使用 Flutter 的 LLDB Init File。没有此文件时，在 iOS 26 及更高版本设备上调试可能会崩溃。
:::

1. Generate Flutter LLDB files.

   生成 Flutter LLDB 文件。

   1. Within your flutter application, re-run `flutter build ios-framework` if
      you haven't already:

      在 Flutter 应用中，若尚未运行，请重新执行 `flutter build ios-framework`：

   ```console
   $ flutter build ios-framework --output=/path/to/MyApp/Flutter/
   ```

   This will generate the LLDB files in the `/path/to/MyApp/Flutter/` directory.

   这会在 `/path/to/MyApp/Flutter/` 目录中生成 LLDB 文件。

1. Set the LLDB Init File.

   设置 LLDB Init File。

   1. Go to **Product > Scheme > Edit Scheme**.

      前往 **Product > Scheme > Edit Scheme**。

   1. Select the **Run** section in the left side bar.

      在左侧边栏选择 **Run** 部分。

   1. Set the **LLDB Init File** to the following:

      将 **LLDB Init File** 设置为以下内容：

      ```console
      $(PROJECT_DIR)/Flutter/flutter_lldbinit
      ```

      If your scheme already has an **LLDB Init File**, you can add Flutter's
      LLDB file to it. The path to Flutter's LLDB Init File must be relative
      to the location of your project's LLDB Init File.

      若 scheme 已有 **LLDB Init File**，可将 Flutter 的 LLDB 文件加入其中。Flutter LLDB Init File 的路径必须相对于项目 LLDB Init File 的位置。

      For example, if your LLDB file is located at `/path/to/MyApp/.lldbinit`,
      you would add the following:

      例如，若 LLDB 文件位于 `/path/to/MyApp/.lldbinit`，可添加以下内容：

      ```console
      command source --relative-to-command-file "Flutter/flutter_lldbinit"
      ```

[static or dynamic frameworks]: https://stackoverflow.com/questions/32591878/ios-is-it-a-static-or-a-dynamic-framework
[static-framework]: https://developer.apple.com/library/archive/technotes/tn2435/_index.html



</Tab>
</Tabs>


## Set local network privacy permissions

## 设置本地网络隐私权限

On iOS 14 and later, enable the Dart multicast DNS service in the
**Debug** version of your iOS app.
This adds [debugging functionalities such as hot-reload and DevTools][]
using `flutter attach`.

在 iOS 14 及更高版本上，请在 iOS app 的 **Debug** 版本中启用 Dart 多播 DNS 服务。
这样可通过 `flutter attach` 使用[热重载和 DevTools 等调试功能][debugging functionalities such as hot-reload and DevTools]。

:::warning
Never enable this service in the **Release** version of your app.
The Apple App Store might reject your app.

切勿在 app 的 **Release** 版本中启用此服务。
Apple App Store 可能会拒绝你的 app。
:::

To set local network privacy permissions only in the Debug version of your app,
create a separate `Info.plist` per build configuration.
SwiftUI projects start without an `Info.plist` file.
If you need to create a property list,
you can do so through Xcode or text editor.
The following instructions assume the default **Debug** and **Release**.
Adjust the names as needed depending on your app's build configurations.

若仅在 app 的 Debug 版本中设置本地网络隐私权限，请为每个构建配置创建单独的 `Info.plist`。
SwiftUI 项目一开始可能没有 `Info.plist` 文件。
如需创建属性列表，可通过 Xcode 或文本编辑器完成。
以下说明假定使用默认的 **Debug** 和 **Release**。
请根据 app 的构建配置按需调整名称。

1. Create a new property list.

   创建新的属性列表。

   1. Open your project in Xcode.

      在 Xcode 中打开项目。

   1. In the **Project Navigator**, click on the project name.

      在 **Project Navigator** 中点击项目名称。

   1. From the **Targets** list in the Editor pane, click on your app.

      在编辑器窗格的 **Targets** 列表中点击你的 app。

   1. Click the **Info** tab.

      点击 **Info** 标签页。

   1. Expand **Custom iOS Target Properties**.

      展开 **Custom iOS Target Properties**。

   1. Right-click on the list and select **Add Row**.

      右键点击列表，选择 **Add Row**。

   1. From the dropdown menu, select **Bonjour Services**.
      This creates a new property list in the project directory
      called `Info`. This displays as `Info.plist` in the Finder.

      在下拉菜单中选择 **Bonjour Services**。
      这会在项目目录中创建一个名为 `Info` 的新属性列表。在 Finder 中显示为 `Info.plist`。

1. Rename the `Info.plist` to `Info-Debug.plist`

   将 `Info.plist` 重命名为 `Info-Debug.plist`

   1. Click on **Info** file in the project list at the left.

      在左侧项目列表中点击 **Info** 文件。

   1. In the **Identity and Type** panel at the right,
      change the **Name** from `Info.plist` to `Info-Debug.plist`.

      在右侧 **Identity and Type** 面板中，将 **Name** 从 `Info.plist` 改为 `Info-Debug.plist`。

1. Create a Release property list.

   创建 Release 属性列表。

   1. In the **Project Navigator**, click on `Info-Debug.plist`.

      在 **Project Navigator** 中点击 `Info-Debug.plist`。

   1. Select **File** > **Duplicate...**.
      You can also press <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>S</kbd>.

      选择 **File** > **Duplicate...**。
      也可按 <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>S</kbd>。

   1. In the dialog box, set the **Save As:** field to
      `Info-Release.plist` and click **Save**.

      在对话框中将 **Save As:** 设为 `Info-Release.plist`，然后点击 **Save**。

1. Add the necessary properties to the **Debug** property list.

   向 **Debug** 属性列表添加必要属性。

   1. In the **Project Navigator**, click on `Info-Debug.plist`.

      在 **Project Navigator** 中点击 `Info-Debug.plist`。

   1. Add the String value `_dartVmService._tcp`
      to the **Bonjour Services** array.

      向 **Bonjour Services** 数组添加字符串值 `_dartVmService._tcp`。

   1. _(Optional)_ To set your desired customized permission dialog text,
      add the key **Privacy - Local Network Usage Description**.

      **（可选）** 若要设置自定义权限对话框文案，请添加键 **Privacy - Local Network Usage Description**。

      <DashImage image="development/add-to-app/ios/project-setup/debug-plist.png" caption="The `Info-Debug` property list with the **Bonjour Services** and **Privacy - Local Network Usage Description** keys added" />

1. Set the target to use different property lists for different build modes.

   设置 target 在不同构建模式下使用不同属性列表。

   1. In the **Project Navigator**, click on your project.

      在 **Project Navigator** 中点击你的项目。

   1. Click the **Build Settings** tab.

      点击 **Build Settings** 标签页。

   1. Click **All** and **Combined** sub-tabs.

      点击 **All** 和 **Combined** 子标签页。

   1. In the Search box, type `plist`.
      This limits the settings to those that include property lists.

      在搜索框中输入 `plist`，将设置限定为与属性列表相关的项。

   1. Scroll through the list until you see **Packaging**.

      滚动列表直至看到 **Packaging**。

   1. Click on the **Info.plist File** setting.

      点击 **Info.plist File** 设置。

   1. Change the **Info.plist File** value
      from `path/to/Info.plist` to `path/to/Info-$(CONFIGURATION).plist`.

      将 **Info.plist File** 的值从 `path/to/Info.plist` 改为 `path/to/Info-$(CONFIGURATION).plist`。

      <DashImage image="development/add-to-app/ios/project-setup/set-plist-build-setting.png" caption="Updating the `Info.plist` build setting to use build mode-specific property lists" />

      This resolves to the path **Info-Debug.plist** in **Debug** and
      **Info-Release.plist** in **Release**.

      在 **Debug** 中解析为 **Info-Debug.plist**，在 **Release** 中解析为 **Info-Release.plist**。

      <DashImage image="development/add-to-app/ios/project-setup/plist-build-setting.png" caption="The updated **Info.plist File** build setting displaying the configuration variations" />

1. Remove the **Release** property list from the **Build Phases**.

   从 **Build Phases** 中移除 **Release** 属性列表。

   1. In the **Project Navigator**, click on your project.

      在 **Project Navigator** 中点击你的项目。

   1. Click the **Build Phases** tab.

      点击 **Build Phases** 标签页。

   1. Expand **Copy Bundle Resources**.

      展开 **Copy Bundle Resources**。

   1. If this list includes `Info-Release.plist`,
      click on it and then click the **-** (minus sign) under it
      to remove the property list from the resources list.

      若列表包含 `Info-Release.plist`，请点击它，再点击下方 **-**（减号）将其从资源列表中移除。

      <DashImage image="development/add-to-app/ios/project-setup/copy-bundle.png" caption="The **Copy Bundle** build phase displaying the **Info-Release.plist** setting. Remove this setting." />

1. The first Flutter screen your Debug app loads prompts
   for local network permission.

   Debug app 加载的第一个 Flutter 界面会提示本地网络权限。

   Click **OK**.

   点击 **OK**。

   _(Optional)_ To grant permission before the app loads, enable
   **Settings > Privacy > Local Network > Your App**.

   **（可选）** 若要在 app 加载前授予权限，请启用 **Settings > Privacy > Local Network > Your App**。

[debugging functionalities such as hot-reload and DevTools]: /add-to-app/debugging


## Mitigate known issue with Apple Silicon Macs

## 缓解 Apple Silicon Mac 上的已知问题

On [Macs running Apple Silicon][apple-silicon],
the host app builds for an `arm64` simulator.
While Flutter supports `arm64` simulators, some plugins might not.
If you use one of these plugins, you might see a compilation error like
**Undefined symbols for architecture arm64**.
If this occurs,
exclude `arm64` from the simulator architectures in your host app.

在 [运行 Apple Silicon 的 Mac][apple-silicon] 上，
宿主应用会为 `arm64` 模拟器构建。
Flutter 支持 `arm64` 模拟器，但部分插件可能不支持。
若使用这类插件，可能看到类似 **Undefined symbols for architecture arm64** 的编译错误。
若出现此情况，请在宿主应用中从模拟器架构中排除 `arm64`。

1. In the **Project Navigator**, click on your project.

   在 **Project Navigator** 中点击项目。

1. Click the **Build Settings** tab.

   点击 **Build Settings** 标签页。

1. Click **All** and **Combined** sub-tabs.

   点击 **All** 与 **Combined** 子标签页。

1. Under **Architectures**, click on **Excluded Architectures**.

   在 **Architectures** 下点击 **Excluded Architectures**。

1. Expand to see the available build configurations.

   展开以查看可用构建配置。

1. Click **Debug**.

   点击 **Debug**。

1. Click the **+** (plus sign).

   点击 **+**（加号）。

1. Select **iOS Simulator**.

   选择 **iOS Simulator**。

1. Double-click in the value column for **Any iOS Simulator SDK**.

   双击 **Any iOS Simulator SDK** 的值列。

1. Click the **+** (plus sign).

   点击 **+**（加号）。

1. Type `arm64` in the **Debug > Any iOS Simulator SDK** dialog box.

   在 **Debug > Any iOS Simulator SDK** 对话框中输入 `arm64`。

   <DashImage image="development/add-to-app/ios/project-setup/excluded-archs.png" caption="Add `arm64` as an excluded architecture for your app" />

1. Press <kbd>Esc</kbd> to close this dialog box.

   按 <kbd>Esc</kbd> 关闭对话框。

1. Repeat these steps for the **Release** build mode.

   对 **Release** 构建模式重复上述步骤。

1. Repeat for any iOS unit test targets.

   对所有 iOS 单元测试 target 重复操作。

## Next steps

## 后续步骤

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

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

[add_to_app code samples]: https://github.com/flutter/samples/tree/main/add_to_app
[add a Flutter screen]: /add-to-app/ios/add-flutter-screen
[Android Studio/IntelliJ]: /tools/android-studio
[build modes of Flutter]: /testing/build-modes
[CocoaPods]: https://cocoapods.org/
[app-size]: /resources/faq#how-big-is-the-flutter-engine
[VS Code]: /tools/vs-code
[News Feed app]: https://github.com/flutter/put-flutter-to-work/tree/022208184ec2623af2d113d13d90e8e1ce722365
[Debugging your add-to-app module]: /add-to-app/debugging/
[apple-silicon]: https://support.apple.com/en-us/116943
[read-only]: https://blog.cocoapods.org/CocoaPods-Specs-Repo/
[updated integration guide]: /add-to-app/ios/project-setup