Flutter项目iOS端Xcode构建出现Module 'cloud_firestore' not found报错求助

前置版本对齐校验 #

• 校验本地CocoaPods版本，执行pod --version，要求版本不低于1.13.0，旧版本CocoaPods对Flutter插件的静态库链接存在兼容性缺陷，可通过sudo gem install cocoapods完成升级
• 检查iOS路径下的Podfile配置，确认最低部署版本设置为platform :ios, '12.0'，低于该版本时cloud_firestore的二进制依赖会被pod进程自动跳过，直接导致模块缺失
• 对齐版本兼容矩阵：cloud_firestore 4.x及以上版本仅支持Flutter 3.13+的构建流程，跨版本搭配旧版Flutter会出现插件加载逻辑失效

全量缓存清理与依赖重装 #

按固定顺序执行操作，跳过步骤会导致缓存残留：

1. 项目根目录执行flutter clean，清空项目构建缓存
2. 进入iOS子目录，执行rm -rf Pods Podfile.lock ~/Library/Developer/Xcode/DerivedData/*，删除本地pod依赖、锁文件、Xcode全局派生数据
3. 回到项目根目录执行flutter pub get，重新拉取插件依赖索引
4. 再次进入iOS目录，先执行pod cache clean cloud_firestore清除旧版pod残留缓存，再执行pod install --repo-update完成依赖安装

Xcode配置修正 #

• 构建时必须打开iOS路径下的Runner.xcworkspace文件，直接打开Runner.xcodeproj会丢失Flutter插件的模块搜索路径，必然触发模块找不到的报错
• 检查Build Settings下的User Header Search Paths配置，确认已包含$(inherited)值
• 临时关闭Bitcode配置：路径为Build Settings -> Enable Bitcode，设置为No。新版Firebase iOS SDK已彻底停止支持Bitcode，开启状态会直接拦截模块链接流程
• 确认Build Phases下的Flutter相关脚本执行顺序位于所有编译步骤之前，未被手动移位

空白项目仍复现的专项排查 #

• 执行flutter doctor -v查看Flutter SDK的安装路径，确认路径中不存在中文、特殊字符，旧版cloud_firestore的pod脚本在非ASCII路径环境下会静默安装失败
• 临时将项目的签名Team设置为None，先执行无签名的Debug构建测试，如果无签名构建可正常完成，说明原有签名配置的hook脚本干扰了pod的模块链接路径

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