MacOS构建Flutter项目时出现FlutterMacOS.h缺失的Firebase Core错误

环境信息 #

• macOS Ventura 13.2.1（Apple M1芯片）
• Flutter 3.10.2
• 最新版Xcode

核心报错 #

构建时触发致命错误：

/Users/alexprice/.pub-cache/hosted/pub.dev/firebase_core-2.13.0/macos/Classes/messages.g.m:9:9: fatal error: 'FlutterMacOS/FlutterMacOS.h' file not found
#import <FlutterMacOS/FlutterMacOS.h>
        ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1 error generated.

同时伴随多个脚本阶段警告（如gRPC-Core、abseil等的"Create Symlinks to Header Folders"脚本未指定输出依赖）。

已尝试操作 #

• 执行过 flutter clean、flutter pub get
• 删除锁文件、pod reintegrate、pod update、pod repo update、pod install
• 已添加Firebase的Google-services配置文件

项目配置 #

pubspec.yaml #

version: 1.0.0+1

environment:
  sdk: '>=3.0.1 <4.0.0'

dependencies:
  cloud_firestore: ^4.0.2
  firebase_auth: ^4.6.1
  firebase_core: ^2.13.0
  firebase_storage: ^11.2.1
  flutter:
    sdk: flutter
  flutter_riverpod: ^2.3.6

macOS Podfile #

platform :osx, '12.0'

# CocoaPods analytics sends network stats synchronously affecting flutter build latency.
ENV['COCOAPODS_DISABLE_STATS'] = 'true'

project 'Runner', {
  'Debug' => :debug,
  'Profile' => :release,
  'Release' => :release,
}

def flutter_root
  generated_xcode_build_settings_path = File.expand_path(File.join('..', 'Flutter', 'ephemeral', 'Flutter-Generated.xcconfig'), __FILE__)
  unless File.exist?(generated_xcode_build_settings_path)
    raise "#{generated_xcode_build_settings_path} must exist. If you're running pod install manually, make sure \"flutter pub get\" is executed first"
  end

  File.foreach(generated_xcode_build_settings_path) do |line|
    matches = line.match(/FLUTTER_ROOT\=(.*)/)
    return matches[1].strip if matches
  end
  raise "FLUTTER_ROOT not found in #{generated_xcode_build_settings_path}. Try deleting Flutter-Generated.xcconfig, then run \"flutter pub get\""
end

require File.expand_path(File.join('packages', 'flutter_tools', 'bin', 'podhelper'), flutter_root)

flutter_macos_podfile_setup

target 'Runner' do
  use_frameworks!
  use_modular_headers!

  flutter_install_all_macos_pods File.dirname(File.realpath(__FILE__))
  target 'RunnerTests' do
    inherit! :search_paths
  end
end

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=macos]"] = "arm64"
        config.build_settings['MACOSX_DEPLOYMENT_TARGET'] = '12.0'
        config.build_settings['ONLY_ACTIVE_ARCH'] = 'YES'
    end
  end
end

解决步骤 #

1. 修复FlutterMacOS框架链接 #

头文件找不到是因为Flutter macOS框架未正确关联到Xcode项目：

• 打开macos目录下的Runner.xcworkspace
• 选中Runner目标，进入Build Phases标签
• 检查Link Binary With Libraries中是否存在FlutterMacOS.framework，若没有则点击+ → Add Other... → Add Files，导航到Flutter SDK目录下的bin/cache/artifacts/engine/darwin-arm64/FlutterMacOS.framework（M1芯片用这个路径，Intel芯片选darwin-x64）添加
• 切换到Build Settings标签，检查Header Search Paths是否包含$(inherited)和${FLUTTER_ROOT}/bin/cache/artifacts/engine/darwin-arm64（对应芯片架构路径）

2. 彻底清理并重构项目 #

执行以下命令清空缓存重新构建：

flutter clean
rm -rf macos/Pods
rm -rf macos/Podfile.lock
rm -rf macos/Runner.xcworkspace
flutter pub get
cd macos
pod install --repo-update
cd ..
flutter build macos

3. 修正Podfile配置错误 #

Podfile中误用了iOS的构建配置方法，替换为macOS专用：
修改post_install部分：

post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_macos_build_settings(target) # 替换原iOS配置方法
    target.build_configurations.each do |config|
        config.build_settings['MACOSX_DEPLOYMENT_TARGET'] = '12.0'
        config.build_settings['ONLY_ACTIVE_ARCH'] = 'YES'
    end
  end
end

4. 消除脚本警告（可选） #

若要解决无输出脚本的警告，可针对每个报错的Pods目标：

• 在Xcode的Pods项目中找到对应目标（如gRPC-Core）
• 进入Build Phases，找到Create Symlinks to Header Folders脚本
• 取消勾选Based on dependency analysis，或添加脚本生成的头文件路径作为输出依赖

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