将 Flutter 应用集成到 iOS 项目

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

• Flutter 3.44 or later
• Xcode 15.0 or later

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.

The legacy integration guide is preserved for reference, but will not receive ongoing maintenance.

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.

The example directory structure resembles the following:

1. Build the FlutterNativeIntegration Swift package

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

   flutter build swift-package --platform ios
   

   content_copy

   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.

2. Add FlutterNativeIntegration to your Xcode project

   1. Open your existing iOS app in Xcode.

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

   3. Navigate to and select the generated FlutterNativeIntegration Swift package and click Add.

   4. Select Reference files in place and click Finish.

   5. 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.

      

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

3. 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
      

      content_copy

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

      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.

      

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

      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.

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

      content_copy

4. Add Pre-action Run Script to Scheme

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

   2. Select your project in the Provide build settings from dropdown.

   3. Set the script to the following:

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

      content_copy
   

5. Add New Run Script Build Phase to Target

   1. Navigate to your target's Build Phases > + > New Run Script Phase

   2. Set the script to the following:

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

      content_copy

   3. Uncheck Based on dependency analysis

   4. Add the following to Input File Lists:

      $(FLUTTER_SWIFT_PACKAGE_OUTPUT)/Scripts/FlutterAssembleInputs.xcfilelist
      

      content_copy
   

6. (Optional) Set LLDB Init File

   Using Flutter's LLDB Init File improves performance when debugging on physical iOS 26+ devices.

   1. Open Product > Scheme > Edit Scheme... > Run (in left side bar).

   2. Set the LLDB Init File to the following path:

      $(FLUTTER_SWIFT_PACKAGE_OUTPUT)/Scripts/flutter_lldbinit
      

      content_copy

      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.

      command source --relative-to-command-file "../my_flutter_app/build/ios/SwiftPackages/Scripts/flutter_lldbinit"
      

      content_copy

在 iOS 14 及更高版本上，请在 iOS app 的 Debug 版本中启用 Dart 多播 DNS 服务。这样可通过 flutter attach 使用热重载和 DevTools 等调试功能。

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

1. Create a new property list.

   1. 创建新的属性列表。

   2. Open your project in Xcode.

      1. 在 Xcode 中打开项目。

   3. In the Project Navigator, click on the project name.

      1. 在 Project Navigator 中点击项目名称。

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

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

   5. Click the Info tab.

      1. 点击 Info 标签页。

   6. Expand Custom iOS Target Properties.

      1. 展开 Custom iOS Target Properties。

   7. Right-click on the list and select Add Row.

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

   8. 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.

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

2. Rename the Info.plist to Info-Debug.plist

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

   2. Click on Info file in the project list at the left.

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

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

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

3. Create a Release property list.

   1. 创建 Release 属性列表。

   2. In the Project Navigator, click on Info-Debug.plist.

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

   3. Select File > Duplicate.... You can also press Cmd + Shift + S.

      1. 选择 File > Duplicate...。也可按 Cmd + Shift + S。

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

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

4. Add the necessary properties to the Debug property list.

   1. 向 Debug 属性列表添加必要属性。

   2. In the Project Navigator, click on Info-Debug.plist.

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

   3. Add the String value _dartVmService._tcp to the Bonjour Services array.

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

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

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

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

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

   2. In the Project Navigator, click on your project.

      1. 在 Project Navigator 中点击你的项目。

   3. Click the Build Settings tab.

      1. 点击 Build Settings 标签页。

   4. Click All and Combined sub-tabs.

      1. 点击 All 和 Combined 子标签页。

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

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

   6. Scroll through the list until you see Packaging.

      1. 滚动列表直至看到 Packaging。

   7. Click on the Info.plist File setting.

      1. 点击 Info.plist File 设置。

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

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

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

      

6. Remove the Release property list from the Build Phases.

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

   2. In the Project Navigator, click on your project.

      1. 在 Project Navigator 中点击你的项目。

   3. Click the Build Phases tab.

      1. 点击 Build Phases 标签页。

   4. Expand Copy Bundle Resources.

      1. 展开 Copy Bundle Resources。

   5. 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.

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

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

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

   点击 OK。

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

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