升级macOS15.3与Xcode16.2后桥接头文件及Flutter依赖问题

近期将macOS升级至15.3（24D60）、Xcode升级至16.2后，包含Swift与Objective-C混合代码的框架项目编译时出现错误：

"Using bridging headers with module interfaces is unsupported"

此前项目运行正常，升级后构建失败。

项目详情 #

• 含Swift与Objective-C混合代码的框架项目
• 原使用MyFramework-Bridging-Header.h桥接头文件向Swift暴露Objective-C代码
• 升级前运行正常

已尝试操作 #

1. 确认Build Settings中Defines Module设为YES
2. 清理构建文件夹后重新构建，错误仍存在
3. 验证Objective-C Bridging Header路径配置正确
4. 替换桥接头文件为模块映射（module.modulemap）与伞头文件（MyFrameworkName.h），并更新Build Settings
5. 替换后出现新错误："flutter not found on AppDelegate"

核心问题 #

1. 升级后为何出现原错误？
2. 使用模块映射时如何解决Flutter找不到的错误？
3. 替换桥接头文件并确保Flutter依赖集成的推荐方案是什么？

附加信息：Xcode16.2、macOS15.3，混合语言框架，含Flutter依赖。

1. 原错误出现原因 #

Xcode 16+（对应macOS 15+）严格执行了模块接口（Module Interfaces）的规则：当框架开启Defines Module = YES时，不再允许同时使用桥接头文件。这是因为模块接口本身是为规范混合语言项目的依赖暴露设计的，桥接头文件的旧模式与模块系统存在冲突，之前的Xcode版本对该限制的校验较宽松，升级后触发了强制校验导致报错。

2. 模块映射下解决Flutter找不到的问题 #

该错误是因为模块映射未正确引入Flutter依赖，可按以下步骤修复：

• 在伞头文件MyFrameworkName.h中添加Flutter相关头文件导入：

  #import <Flutter/Flutter.h>
  #import <FlutterPluginRegistrant/GeneratedPluginRegistrant.h>
  // 其他项目需要的Flutter相关头文件
  

• 检查module.modulemap配置，确保框架模块正确包含伞头，必要时显式引入Flutter模块：

  framework module MyFrameworkName {
      umbrella header "MyFrameworkName.h"
      export *
      module * { export * }
  
      // 若伞头导入未生效，可添加此段显式引用
      module Flutter {
          header "<Flutter/Flutter.h>"
          export *
      }
  }
  

• 确认Build Settings中的Header Search Paths包含Flutter头文件路径，示例路径：$(FLUTTER_ROOT)/bin/cache/artifacts/engine/ios

3. 替换桥接头文件+Flutter依赖集成的推荐方案 #

完整迁移步骤如下：

1. 移除桥接头文件配置：在Build Settings中清空Objective-C Bridging Header路径，备份后删除原MyFramework-Bridging-Header.h文件。
2. 创建伞头文件：新建与框架Target同名的MyFrameworkName.h，将原桥接头文件中需要暴露给Swift的Objective-C头文件全部导入，同时加入Flutter相关头文件（参考步骤2的导入内容）。
3. 配置模块映射：在框架的Supporting Files目录下创建module.modulemap，内容如下：

   framework module MyFrameworkName {
       umbrella header "MyFrameworkName.h"
       export *
       module * { export * }
   }
   

4. 更新Build Settings：
   • 保持Defines Module = YES
   • 设置Module Map File为你的模块映射文件路径，示例：$(SRCROOT)/MyFramework/module.modulemap
   • 确认Umbrella Header指向MyFrameworkName.h
5. 处理Flutter依赖：
   • 执行flutter clean和flutter pub get重新生成依赖
   • 在AppDelegate等文件中，使用模块方式导入Flutter：Swift用import Flutter，Objective-C用#import <Flutter/Flutter.h>
6. 清理重建：执行Cmd+Shift+K清理构建文件夹，再重新构建项目。

内容的提问来源于stack exchange，提问作者Machhindra Neupane