Flutter iOS构建报错：大量‘无法构建模块’及预编译头生成失败

问题概述 #

Flutter开发的Android应用运行正常，但通过Xcode构建iOS版本时，出现大量“无法构建模块”错误，同时伴随“无法生成预编译头”问题，已尝试多种常规方案未解决。

错误日志 #

failed to emit precompiled header '/Users/emrecaglar/Library/Developer/Xcode/DerivedData/Runner-fxwxdylmxkcpzxeqrhwvvfdkrcwt/Build/Intermediates.noindex/PrecompiledHeaders/Runner-Bridging-Header-swift_3CL9TF27LCUZ1-clang_39V4VM58ZMBMS.pch' for bridging header '/Users/emrecaglar/Documents/Development/Projects/itirafcom/ios/Runner/Runner-Bridging-Header.h'

/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/QuartzCore.framework/Headers/CABase.h
/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/QuartzCore.framework/Headers/CABase.h:16:10 could not build module 'CoreFoundation'

/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/CFNetwork.framework/Headers/CFNetwork.h
/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/CFNetwork.framework/Headers/CFNetwork.h:18:10 could not build module 'CoreFoundation'

/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/CoreFoundation.framework/Headers/CFStream.h
/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/CoreFoundation.framework/Headers/CFStream.h:20:10 could not build module 'Dispatch'

/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/CoreGraphics.framework/Headers/CGBase.h
/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/CoreGraphics.framework/Headers/CGBase.h:12:10 could not build module 'CoreFoundation'

/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/CoreMedia.framework/Headers/CMBase.h
/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/CoreMedia.framework/Headers/CMBase.h:167:10 could not build module 'CoreFoundation'

/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/CoreAudioTypes.framework/Headers/CoreAudioBaseTypes.h
/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/CoreAudioTypes.framework/Headers/CoreAudioBaseTypes.h:18:10 could not build module 'CoreFoundation'

/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/CoreAudio.framework/Headers/CoreAudioTypes.h
/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/CoreAudio.framework/Headers/CoreAudioTypes.h:4:10 could not build module 'CoreAudioTypes'

/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/CoreImage.framework/Headers/CoreImageDefines.h
/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/CoreImage.framework/Headers/CoreImageDefines.h:17:10 could not build module 'CoreGraphics'

/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/CoreText.framework/Headers/CTFontTraits.h
/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/CoreText.framework/Headers/CTFontTraits.h:14:10 could not build module 'CoreFoundation'

/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/CoreVideo.framework/Headers/CVBase.h
/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/CoreVideo.framework/Headers/CVBase.h:30:10 could not build module 'CoreFoundation'

/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/usr/include/dispatch/dispatch.h
/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/usr/include/dispatch/dispatch.h:63:10 could not build module 'os_object'

/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/OpenGLES.framework/Headers/EAGL.h
/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/OpenGLES.framework/Headers/EAGL.h:8:10 could not build module 'Foundation'

/Users/emrecaglar/Library/Developer/Xcode/DerivedData/Runner-fxwxdylmxkcpzxeqrhwvvfdkrcwt/Build/Products/Debug-iphonesimulator/Flutter.framework/Headers/FlutterAppDelegate.h
/Users/emrecaglar/Library/Developer/Xcode/DerivedData/Runner-fxwxdylmxkcpzxeqrhwvvfdkrcwt/Build/Products/Debug-iphonesimulator/Flutter.framework/Headers/FlutterAppDelegate.h:8:9 could not build module 'UIKit'

/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/Foundation.framework/Headers/Foundation.h
/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/Foundation.framework/Headers/Foundation.h:6:10 could not build module 'CoreFoundation'

/Users/emrecaglar/Documents/Development/Projects/itirafcom/ios/Runner/GeneratedPluginRegistrant.h
/Users/emrecaglar/Documents/Development/Projects/itirafcom/ios/Runner/GeneratedPluginRegistrant.h:10:9 could not build module 'Flutter'

/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/ImageIO.framework/Headers/ImageIOBase.h
/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/ImageIO.framework/Headers/ImageIOBase.h:16:10 could not build module 'CoreFoundation'

/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/IOSurface.framework/Headers/IOSurfaceBase.h
/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/IOSurface.framework/Headers/IOSurfaceBase.h:36:10 could not build module 'CoreFoundation'

/Users/emrecaglar/Documents/Development/Projects/itirafcom/ios/Pods/Firebase/CoreOnly/Sources/module.modulemap
/Users/emrecaglar/Documents/Development/Projects/itirafcom/ios/Pods/Firebase/CoreOnly/Sources/module.modulemap:1:8 redefinition of module 'Firebase'

/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/Metal.framework/Headers/MTLTypes.h
/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/Metal.framework/Headers/MTLTypes.h:8:9 could not build module 'Foundation'

/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/FileProvider.framework/Headers/NSFileProviderDomain.h
/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/FileProvider.framework/Headers/NSFileProviderDomain.h:8:9 could not build module 'Foundation'

/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/UserNotifications.framework/Headers/NSString+UserNotifications.h
/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/UserNotifications.framework/Headers/NSString+UserNotifications.h:8:9 could not build module 'Foundation'

/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/usr/include/os/object.h
/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/usr/include/os/object.h:114:9 could not build module 'ObjectiveC'

/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/Security.framework/Headers/SecBase.h
/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/Security.framework/Headers/SecBase.h:28:10 could not build module 'CoreFoundation'

/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/UIKit.framework/Headers/UIKit.h
/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/System/Library/Frameworks/UIKit.framework/Headers/UIKit.h:8:9 could not build module 'Foundation'

/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/usr/include/os/workgroup_base.h
/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator16.1.sdk/usr/include/os/workgroup_base.h:19:10 could not build module 'os_object'

本地开发环境 #

• macOS 13.0.1 (22A400) Ventura
• Xcode 14.1
• Flutter版本：

%flutter --version
Flutter 3.3.10 • channel stable • https://github.com/flutter/flutter.git
Framework • revision 135454af32 (7 days ago) • 2022-12-15 07:36:55 -0800
Engine • revision 3316dd8728
Tools • Dart 2.18.6 • DevTools 2.15.0

• Flutter Doctor检查结果：

%flutter doctor
Doctor summary (to see all details, run flutter doctor -v):
[✓] Flutter (Channel stable, 3.3.10, on macOS 13.0.1 22A400 darwin-arm, locale en-US)
[✓] Android toolchain - develop for Android devices (Android SDK version 33.0.1)
[✓] Xcode - develop for iOS and macOS (Xcode 14.1)
[✓] Chrome - develop for the web
[✓] Android Studio (version 2021.3)
[✓] IntelliJ IDEA Ultimate Edition (version 2022.3)
[✓] Connected device (2 available)
[✓] HTTP Host Availability

• No issues found!

已尝试方案 #

• 重置Package缓存并更新至最新版本
• 清理Derived文件夹
• 删除Flutter项目的整个iOS文件夹并重新生成
• 清理podfile.lock和Pods文件夹后执行pod install
• 检查项目目标iOS版本为11
• 注释Podfile中的iOS 11版本进行尝试
• 将“Enable Modules”（C和Objective-C）设置为false
• 重新安装Command Line Tools和Xcode

解决方案建议 #

1. 修复Firebase模块重定义问题 #

错误日志中明确出现redefinition of module 'Firebase'，这是核心问题之一：

• 打开项目的Podfile，检查Firebase相关依赖，确保没有同时引入Firebase/Core和Firebase/CoreOnly，保留其中一种即可
• 执行以下命令彻底清理Pods环境：

  cd ios
  pod deintegrate
  rm Podfile.lock
  rm -rf Pods
  pod install
  

2. 调整Xcode项目Build Settings配置 #

• 打开Xcode，选择Runner target，进入Build Settings：
  • 找到Build Active Architecture Only，将Debug模式设置为YES
  • 找到Precompile Prefix Header，设置为NO，跳过预编译头构建
  • 检查Header Search Paths和Framework Search Paths，移除所有无效或重复的路径，确保系统框架路径（如$(SDKROOT)/System/Library/Frameworks/）存在且正确

3. 重置Xcode开发者工具 #

• 执行终端命令重置Xcode命令行工具：

  sudo xcode-select --reset
  

• 打开Xcode，选择Xcode > Settings > Locations，确认Command Line Tools选择的是当前安装的Xcode 14.1版本
• 重启Xcode后重新构建项目

4. 适配Apple Silicon架构（M1/M2芯片） #

针对Apple Silicon设备的架构兼容问题：

• 在Xcode的Runner target的Build Settings中，找到Excluded Architectures，在Debug模式的模拟器配置中添加arm64
• 打开Podfile，添加以下配置：

  post_install do |installer|
    installer.pods_project.targets.each do |target|
      flutter_additional_ios_build_settings(target)
      target.build_configurations.each do |config|
        config.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = 'arm64'
      end
    end
  end
  

• 重新执行pod install，然后尝试构建

5. 排查项目配置损坏问题 #

如果以上方案无效，尝试创建一个全新的Flutter项目，逐步添加原项目的依赖和代码，确认是否能正常构建，以此排查是否是原项目的配置文件损坏导致的问题

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