# 将 Flutter 应用集成到 iOS 项目
> 了解如何将 Flutter 应用集成到你现有的 iOS 项目中。
:::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 iOS application using Swift packages.
你可以使用 Swift package 将 Flutter UI 组件
逐步添加到你现有的 iOS 应用中。
## 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}
### 从旧版集成方式迁移（如适用）
If you've already integrated Flutter into your iOS app
using CocoaPods or embedded frameworks,
you must first remove that integration
before following the Swift Package Manager instructions below.
如果你已经使用 CocoaPods 或嵌入式 framework
将 Flutter 集成到 iOS 应用中，
则必须先移除该集成，
再按照下面的 Swift Package Manager 说明操作。
Expand to see instructions to migrate from CocoaPods integration展开查看从 CocoaPods 集成迁移的说明
If your app was previously integrated using CocoaPods,
you must first remove the Flutter installation code from your Podfile.
如果你的应用之前是通过 CocoaPods 集成的，
则必须先从 Podfile 中移除 Flutter 安装代码。
1. Remove Flutter installation code from your Podfile
从 Podfile 中移除 Flutter 安装代码。
```ruby title="MyApp/Podfile" diff
- flutter_application_path = '../my_flutter'
- load File.join(flutter_application_path, '.ios', 'Flutter', 'podhelper.rb')
- install_all_flutter_pods(flutter_application_path)
- flutter_post_install(installer) if defined?(flutter_post_install)
```
1. Run `pod install`.
运行 `pod install`。
Expand to see instructions to migrate from embedded frameworks integration展开查看从嵌入式 framework 集成迁移的说明
If your app was previously integrated using frameworks
generated by the `flutter build ios-framework` command,
you must first remove the frameworks from your Xcode project.
如果你的应用之前是通过 `flutter build ios-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`, `Flutter.xcframework`,
`FlutterPluginRegistrant.xcframework`,
and any Flutter plugins' `xcframework` files.
这包括 `App.xcframework`、`Flutter.xcframework`、
`FlutterPluginRegistrant.xcframework`，
以及所有 Flutter 插件的 `xcframework` 文件。
1. Remove the Flutter pod from your Podfile
从 Podfile 中移除 Flutter pod。
```ruby title="MyApp/Podfile" diff
- pod 'Flutter', :podspec => '/path/to/MyApp/Flutter/[build mode]/Flutter.podspec'
```
1. Run `pod install`.
运行 `pod install`。
The [legacy integration guide][] is preserved for reference,
but will not receive ongoing maintenance.
[旧版集成指南][legacy integration guide] 仍保留以供参考，
但不再持续维护。
### Organize your projects relative to each other {: #organize-projects-relatively}
### 组织各项目的相对位置
This guide assumes that your existing iOS app
and your Flutter app or module reside in sibling directories.
If you have a different directory structure,
you will need to adjust the example relative paths accordingly.
本指南假定你现有的 iOS 应用
与你的 Flutter 应用或模块位于同级目录中。
如果你的目录结构不同，
则需要相应地调整示例中的相对路径。
:::note
If integrating for the first time,
it's recommended to use a Flutter application (instead of a module).
Run the following command to create a new Flutter application:
如果是首次集成，
建议使用 Flutter 应用（而非模块）。
运行以下命令创建一个新的 Flutter 应用：
```console
flutter create my_flutter_app
```
:::
The example directory structure resembles the following:
示例目录结构如下所示：
- my_flutter_app/
- ios/
- lib/
- main.dart
- MyNativeApp/
- MyNativeApp.xcodeproj/
- my_flutter_app/
- .ios/
- lib/
- main.dart
- MyNativeApp/
- MyNativeApp.xcodeproj/
## Integrate with Swift Package Manager {: #integrate-with-swiftpm}
## 使用 Swift Package Manager 集成
1. Build the FlutterNativeIntegration Swift package
构建 FlutterNativeIntegration Swift package
Within your Flutter application or module, run the following command:
在你的 Flutter 应用或模块中，运行以下命令：
```console
flutter build swift-package --platform ios
```
This will generate the following directories:
这会生成以下目录：
- my_flutter_app/build/ios/SwiftPackages/
- FlutterNativeIntegration/ (A Swift package)
- Scripts/ (Directory of scripts and other files needed)
You can optionally change the location of this output
with the `--output` flag.
你也可以通过 `--output` 标志更改此输出的位置。
1. Add FlutterNativeIntegration to your Xcode project
将 FlutterNativeIntegration 添加到你的 Xcode 项目
1. Open your existing iOS app in Xcode.
在 Xcode 中打开你现有的 iOS 应用。
1. In the Project navigator, right click on your project
and select **Add Files to "MyNativeApp"...**
在 Project navigator（项目导航器）中右键点击你的项目，
选择 **Add Files to "MyNativeApp"...**（向 "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 输出目录
移动为与原生应用同级的目录。
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`。
1. Add build settings
添加构建设置
1. In the **Build Settings** tab,
set the location of the Flutter app's Swift package output directory:
```
FLUTTER_SWIFT_PACKAGE_OUTPUT=$SRCROOT/../my_flutter_app/build/ios/SwiftPackages
```
在 **Build Settings**（构建设置）标签页中，
设置 Flutter 应用的 Swift package 输出目录的位置：
```
FLUTTER_SWIFT_PACKAGE_OUTPUT=$SRCROOT/../my_flutter_app/build/ios/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`.
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` 构建设置
设为这些值之一。
1. (Optional) Allow Xcode to re-build your Flutter app.
（可选）允许 Xcode 重新构建你的 Flutter 应用。
Add the below 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 Flutter to be installed 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. Add Pre-action Run Script to Scheme
向 Scheme 添加 Pre-action 运行脚本
1. Open **Product** > **Scheme** > **Edit Scheme...**
> **Build** (in left side bar) > **Pre-action** > **+**
> **New Run Script Action**
打开 **Product** > **Scheme** > **Edit Scheme...**
> **Build**（左侧边栏）> **Pre-action** > **+**
> **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
```
1. Add New Run Script Build Phase to Target
向 Target 添加新的运行脚本构建阶段
1. Navigate to your target's **Build Phases**
> **+** > **New Run Script Phase**
进入你的 target 的 **Build Phases**（构建阶段）
> **+** > **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
```
1. (Optional) Set LLDB Init File
（可选）设置 LLDB Init File
Using Flutter's LLDB Init File improves performance
when debugging on physical iOS 26+ devices.
在 iOS 26+ 真机上调试时，使用 Flutter 的 LLDB Init File 可以提升性能。
1. Open **Product** > **Scheme** > **Edit Scheme...** > **Run** (in left side bar).
打开 **Product** > **Scheme** > **Edit Scheme...** > **Run**（左侧边栏）。
1. Set the **LLDB Init File** to the following path:
将 **LLDB Init File** 设为以下路径：
```
$(FLUTTER_SWIFT_PACKAGE_OUTPUT)/Scripts/flutter_lldbinit
```
Alternatively, 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 的位置。
```
command source --relative-to-command-file "../my_flutter_app/build/ios/SwiftPackages/Scripts/flutter_lldbinit"
```
{:.steps}
## Set local network privacy permissions {: #local-network-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 Cmd + Shift + S.
选择 **File** > **Duplicate...**。
也可按 Cmd + Shift + S。
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**。
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`。
This resolves to the path **Info-Debug.plist** in **Debug** and
**Info-Release.plist** in **Release**.
在 **Debug** 中解析为 **Info-Debug.plist**，在 **Release** 中解析为 **Info-Release.plist**。
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`，请点击它，再点击下方 **-**（减号）将其从资源列表中移除。
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
## Next steps
## 后续步骤
You can now [add a Flutter screen][] to your existing iOS app.
现在你可以向现有的 iOS 应用 [添加 Flutter 页面][add a Flutter screen] 了。
[add a Flutter screen]: /add-to-app/ios/add-flutter-screen
[legacy integration guide]: /add-to-app/ios/project-setup-legacy
[build modes]: /testing/build-modes