构建Flutter iOS应用提示'Flutter/Flutter.h' file not found如何解决

基础修复流程（80%的场景可以通过这步解决） #

按顺序在项目根目录执行以下命令：

# 清理Flutter构建缓存
flutter clean
# 重新拉取Dart依赖
flutter pub get
# 进入iOS目录重装CocoaPods依赖
cd ios
pod deintegrate
pod install --repo-update

执行完成后完全退出Xcode，重新打开ios/Runner.xcworkspace文件（注意不要打开Runner.xcodeproj，该文件缺少Pods依赖关联配置，必然会报头文件找不到错误），再尝试编译。

配置项排查 #

如果基础流程执行后仍然报错，按以下项逐一检查：

• 检查Header Search Paths配置
  在Xcode中选中Runner Target，切换到Build Settings标签，搜索Header Search Paths，确认存在以下两个路径项，且右侧选项设置为recursive：
  • $(SRCROOT)/..
  • $(FLUTTER_ROOT)/bin/cache/pkg/sky_engine
    注意：不要硬编码本地Flutter的绝对安装路径，必须使用上述变量路径，否则跨设备协作、升级Flutter版本时会重复触发该错误
• 检查Podfile完整性
  打开ios/Podfile，确认文件没有被手动修改破坏Flutter的默认加载逻辑：
  1. 文件头部存在Flutter路径定义与Podhelper加载逻辑，格式如下：

     flutter_application_path = '../'
     load File.join(flutter_application_path, 'ios', 'Flutter', 'Podhelper.rb')
     

  2. 如果项目中引入了需要动态链接的插件，不要直接全局开启use_frameworks!，替换为静态链接配置避免冲突：

     use_frameworks! :linkage => :static
     

  如果Podfile已经被改乱，可以先备份自定义的iOS配置（比如权限描述、签名配置），删除ios目录下的Podfile、Podfile.lock、Pods文件夹，回到项目根目录执行flutter create .重新生成标准iOS项目配置，再还原自定义配置即可。
• 检查版本兼容性
  在终端执行flutter doctor，根据输出确认Xcode版本、Flutter版本没有兼容问题，如果是刚升级Flutter/Xcode后出现的报错，执行flutter precache重新拉取对应平台的构建缓存文件。

特殊场景处理 #

• M系列芯片Mac适配问题：找到终端应用（含iTerm等第三方终端），右键勾选「使用Rosetta打开」，重启终端后重新执行基础修复流程的命令，再打开Xcode编译。
• Flutter混编原生项目场景：确认是通过CocoaPods方式引入Flutter模块，没有直接将Flutter源码文件拖入原生项目，Podfile中正确配置了Flutter模块的本地路径，pod install完成后Pods目录下存在Flutter对应的头文件目录。
• 多环境构建配置场景：如果自定义了Build Configuration，需要在Podfile中为自定义配置匹配对应的Flutter构建模式，否则CocoaPods不会为自定义配置链接Flutter依赖。

内容的提问来源于stack exchange，提问作者Hajer Malik