Flutter升级至3.3.8后出现'Flutter/Flutter.h'文件未找到问题

问题背景 #

我维护一个集成Flutter的iOS项目，之前用Flutter 3.0.3版本运行完全正常。因为项目里用Matrix4.setEntry实现的动画在长时间运行后会卡顿，查社区Issue说升级到3.3.0以上版本能解决这个问题，于是我把Flutter升级到了3.3.8，结果编译iOS项目时直接报错'Flutter/Flutter.h' file not found。

排查信息 #

1. flutter doctor检测无异常：

Doctor summary (to see all details, run flutter doctor -v):
[✓] Flutter (Channel stable, 3.3.8, on macOS 12.6 21G115 darwin-x64, locale
    zh-Hans-CN)
[✓] Android toolchain - develop for Android devices (Android SDK version 33.0.0)
[✓] Xcode - develop for iOS and macOS (Xcode 13.4.1)
[✓] Chrome - develop for the web
[✓] Android Studio (version 2021.2)
[✓] IntelliJ IDEA Ultimate Edition (version 2021.2.4)
[✓] VS Code (version 1.71.2)
[✓] Connected device (2 available)
[✓] HTTP Host Availability
• No issues found!

2. 升级后发现Pods/Development pods/Flutter目录下没有了Frameworks文件夹，查看Flutter.podspec里面有注释说“Framework linking is handled by Flutter tooling, not CocoaPods”，但我搞不懂这个逻辑到底怎么运作。
3. 查看podhelper.rb里的代码，发现Flutter.framework的嵌入脚本是在编译后执行的，怀疑是嵌入时机太晚，导致编译时找不到头文件。
4. 已经试过所有清理缓存的操作：flutter clean、pod deintegrate、删除Podfile.lock、删除CocoaPods缓存、删除Xcode DerivedData等，排除了缓存或者CocoaPods本身的问题。
5. 降级回3.0.3版本后，项目又能正常编译运行了。

解决方案 #

1. 补全Xcode的头文件和框架搜索路径 #

Flutter 3.3+ 不再通过CocoaPods管理Framework链接，需要手动在Xcode里配置路径：

• 打开iOS项目的.xcworkspace
• 进入项目target的Build Settings
• 在Header Search Paths中添加$(FLUTTER_ROOT)/bin/cache/artifacts/engine/ios，勾选recursive
• 在Framework Search Paths中添加同样的路径，勾选recursive

2. 重置Flutter与iOS项目的链接 #

执行以下命令彻底清理并重建依赖：

flutter clean
cd ios
pod deintegrate
rm Podfile.lock
rm -rf ~/Library/Caches/CocoaPods
rm -rf Pods
rm -rf ~/Library/Developer/Xcode/DerivedData
cd ..
flutter pub get
cd ios
pod install

3. 调整Build Phases的脚本执行顺序 #

确保Flutter的嵌入脚本在CocoaPods嵌入之前执行：

• 打开Xcode项目的target，进入Build Phases
• 检查是否有一个Run Script阶段，内容是：

  "$FLUTTER_ROOT/packages/flutter_tools/bin/xcode_backend.sh" build
  "$FLUTTER_ROOT/packages/flutter_tools/bin/xcode_backend.sh" embed
  

• 如果没有，手动添加这个Run Script，并把它拖拽到[CP] Embed Pods Frameworks阶段的前面

4. 手动嵌入Flutter.framework #

如果上面的步骤没用，手动把Flutter.framework添加到项目中：

• 找到路径$FLUTTER_ROOT/bin/cache/artifacts/engine/ios/Flutter.framework
• 把它拖到Xcode项目的Frameworks, Libraries, and Embedded Content里
• 在右侧属性面板设置Embed为Embed & Sign

5. 升级Xcode版本（可选） #

当前用的Xcode 13.4.1，Flutter 3.3.8对Xcode 14及以上版本兼容性更好，要是条件允许，可以升级Xcode后再试编译。

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