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

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

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

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

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

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

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

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

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

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

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

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

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

• 链接并嵌入动态 framework。

• 链接静态 framework。切勿嵌入它们。

Flutter plugin 可能生成 静态或动态 framework。请链接静态 framework，切勿 嵌入它们。

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

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

1. 选择要链接的 framework。

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

   2. 点击 Build Phases 标签页。

   3. 展开 Link Binary With Libraries。

      

   4. 点击 +（加号）。

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

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

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

      

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

   1. 打开 Finder。

   2. 导航到 /path/to/MyApp/ 目录。

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

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

      

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

      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>";
      };
      

      content_copy

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

      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>";
      };
      

      content_copy

3. 更新搜索路径。

   1. 点击 Build Settings 标签页。

   2. 导航到 Search Paths

   3. 双击 Framework Search Paths 右侧。

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

   5. 输入 $(inherited)，然后按 Enter。

   6. 点击 +（加号）。

   7. 输入 $(PROJECT_DIR)/Flutter/$(CONFIGURATION)/，然后按 Enter。

      

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

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

1. 导航到 General > Frameworks, Libraries, and Embedded Content。

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

   

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

3. 点击 Build Phases 标签页。

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

   

5. 构建项目。

   1. 在 Xcode 中打开 MyApp.xcworkspace。

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

   2. 选择 Product > Build，或按 Cmd + B。

1. 生成 Flutter LLDB 文件。

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

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

   content_copy

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

2. 设置 LLDB Init File。

   1. 前往 Product > Scheme > Edit Scheme。

   2. 在左侧边栏选择 Run 部分。

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

      $(PROJECT_DIR)/Flutter/flutter_lldbinit
      

      content_copy

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

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

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

      content_copy

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

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

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

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

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

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

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

此方法仅适用于 beta 或 stable 发布渠道。

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

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

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

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

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

pod 'Flutter', :podspec => '/path/to/MyApp/Flutter/[build mode]/Flutter.podspec'

Flutter plugin 可能生成 静态或动态 framework。请链接静态 framework，切勿 嵌入它们。

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

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

1. 选择要链接的 framework。

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

   2. 点击 Build Phases 标签页。

   3. 展开 Link Binary With Libraries。

      

   4. 点击 +（加号）。

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

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

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

      

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

   1. 打开 Finder。

   2. 导航到 /path/to/MyApp/ 目录。

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

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

      

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

      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>";
      };
      

      content_copy

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

      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>";
      };
      

      content_copy

3. 更新搜索路径。

   1. 点击 Build Settings 标签页。

   2. 导航到 Search Paths

   3. 双击 Framework Search Paths 右侧。

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

   5. 输入 $(inherited)，然后按 Enter。

   6. 点击 +（加号）。

   7. 输入 $(PROJECT_DIR)/Flutter/$(CONFIGURATION)/，然后按 Enter。

      

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

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

1. 导航到 General > Frameworks, Libraries, and Embedded Content。

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

   

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

3. 点击 Build Phases 标签页。

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

   

5. 构建项目。

   1. 在 Xcode 中打开 MyApp.xcworkspace。

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

   2. 选择 Product > Build，或按 Cmd + B。

1. 生成 Flutter LLDB 文件。

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

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

   content_copy

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

2. 设置 LLDB Init File。

   1. 前往 Product > Scheme > Edit Scheme。

   2. 在左侧边栏选择 Run 部分。

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

      $(PROJECT_DIR)/Flutter/flutter_lldbinit
      

      content_copy

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

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

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

      content_copy