Flutter iOS 编译错误怎么解决？16 个 pod install 与编译报错
Flutter iOS 编译错误多出在 pod install 和最低部署目标：Podfile 没写 platform、插件要求更高的 iOS 版本、Specs 索引过旧或没先 flutter pub get。本文按报错原文、原因、改法整理 16 个常见错误。
Flutter iOS 编译错误大多数出在 pod install 和最低部署目标上：Podfile 没写 platform、插件要求更高的 iOS 版本、本地 Specs 索引过旧，或者还没执行 flutter pub get 就跑了 pod install。这篇按「报错原文 → 原因 → 改法」整理了 16 个常见错误，先看总表找到你的报错，再跳到对应小节。报错文本取自 CocoaPods、Flutter 模板和 Apple 文档原文，截至 2026 年 10 月。
Flutter iOS 编译错误出在哪一步？
同一个插件问题，在不同阶段的报错长得完全不一样。先确认卡在哪一步，排查范围能缩小一半。
| 阶段 | 典型表现 | 先查什么 |
|---|---|---|
pod install |
输出里有 [!] 开头的行 |
Podfile、部署目标、网络、CocoaPods 版本 |
| 编译 | 报找不到模块、头文件，或 Run Script 阶段失败 | 是否构建了 Runner.xcworkspace、Flutter 环境是否准备好 |
| 签名与链接 | 证书、描述文件、架构相关的报错 | 证书目录、插件自带的二进制库 |
| 上传 App Store Connect | 收到 ITMS 开头的邮件 | 第三方 SDK 的隐私清单 |
16 个报错怎么快速对照？
| # | 报错（节选） | 原因 | 改法 |
|---|---|---|---|
| 1 | Generated.xcconfig must exist |
还没生成 Flutter 的 iOS 配置 | 先 flutter pub get，再 pod install |
| 2 | FLUTTER_ROOT not found in … |
Generated.xcconfig 内容不完整 | 删掉它，重新 flutter pub get |
| 3 | Automatically assigning platform … because no platform was specified |
Podfile 的 platform 行被注释 | 取消注释并写上版本 |
| 4 | required a higher minimum deployment target |
插件要求的 iOS 版本比工程高 | 提高 Podfile 和 Runner 的部署目标 |
| 5 | out-of-date source repos |
本地 Specs 索引太旧 | pod install --repo-update |
| 6 | CDN: trunk URL couldn't be downloaded |
访问 CocoaPods CDN 失败 | 重试，或换镜像源 |
| 7 | Unable to find compatibility version string for object version |
CocoaPods 太旧，读不了新版工程文件 | 升级 CocoaPods |
| 8 | Unable to determine Swift version for the following pods |
Runner 没设 SWIFT_VERSION | 给 Runner 设置 Swift 版本 |
| 9 | transitive dependencies that include statically linked binaries |
动态框架依赖了静态库 | 改用静态链接，或升级插件 |
| 10 | The sandbox is not in sync with the Podfile.lock |
拉代码后 Podfile.lock 变了 | 重新 pod install |
| 11 | module 'xxx' not found / no such module |
构建了 .xcodeproj，或没装 pods |
装 pods，构建 .xcworkspace |
| 12 | 'Flutter/Flutter.h' file not found、Run Script 阶段报错 |
Flutter 环境没准备好 | 带工程路径重新体检 |
| 13 | No signing certificate matching "…" found |
证书目录里没有对应证书 | 放入证书，或改签名设置 |
| 14 | 链接时提示某个库不是为 iOS 真机 arm64 构建的 | 插件自带的二进制库缺少真机架构 | 升级插件，检查 EXCLUDED_ARCHS |
| 15 | requires minimum platform version … but this target supports … |
SPM 插件要求更高的 iOS 版本 | 提高 Runner 的部署目标 |
| 16 | ITMS-91061 邮件 | 第三方 SDK 缺少隐私清单 | 升级插件到带隐私清单的版本 |
pod install 阶段报错怎么改？
1. Generated.xcconfig must exist
1[!] Invalid `Podfile` file: .../ios/Flutter/Generated.xcconfig must exist. If you're running pod install manually, make sure flutter pub get is executed first
Flutter 生成的 Podfile 会读取 ios/Flutter/Generated.xcconfig 来找 Flutter SDK 的位置。这个文件不进版本库，刚克隆下来的工程、执行过 flutter clean 的工程都没有它。
在工程根目录先执行 flutter pub get，再进 ios 目录 pod install。在 Windows、Linux 上用 KXBuild 时，顺序是先带工程路径运行体检，再 pod install，见文末在 KXBuild 里构建。
2. FLUTTER_ROOT not found
1FLUTTER_ROOT not found in .../ios/Flutter/Generated.xcconfig. Try deleting Generated.xcconfig, then run flutter pub get
文件存在但内容不对，常见于换了 Flutter 安装位置，或者把别人电脑上的 Generated.xcconfig 提交进了仓库。按提示删掉这个文件，重新 flutter pub get。顺手检查 .gitignore，不要把它提交上去。
3. Podfile 没有设置 platform
1[!] Automatically assigning platform `iOS` with version `13.0` on target `Runner` because no platform was specified. Please specify a platform for this target in your Podfile.
Flutter 模板生成的 Podfile 第一行默认是注释掉的 # platform :ios, '…'。没有这一行时，CocoaPods 会自己选一个版本，并打印这条警告，版本号随工程而变。它本身不阻止安装，但后面加插件时容易接着报第 4 条。
打开 ios/Podfile，取消注释并写上版本，和 Runner 的部署目标保持一致。
1platform :ios, '15.0'
按 Flutter 官方的支持平台说明，截至 2026 年 10 月，Flutter 支持 iOS 15 及以上，iOS 14 及更早已不支持，所以填 15.0 或更高。
4. 插件要求更高的最低部署目标
1[!] CocoaPods could not find compatible versions for pod "xxx":
2 ...
3Specs satisfying the `xxx (...)` dependency were found, but they required a higher minimum deployment target.
插件（或它依赖的原生库）声明的最低 iOS 版本，比 Podfile 里 platform 写的高。
- 在插件的 pub.dev 页面或
ios/*.podspec里查它要求的版本。 - 把 Podfile 的
platform :ios改到不低于这个版本。 - 把 Runner 的
IPHONEOS_DEPLOYMENT_TARGET改成同一个值。 - 重新
pod install。
Runner 的部署目标在 Flutter 工程里写在工程级设置上。在 Windows、Linux 上可以用工程设置编辑器改 Deployment 一栏，也可以用命令。
1kxbuild project add-setting -k IPHONEOS_DEPLOYMENT_TARGET -v 15.0 -P .\ios\Runner.xcodeproj
不要反过来把插件降级到很老的版本来迁就低版本 iOS，老版本往往缺少隐私清单，上传时会遇到第 16 条。
5. Specs 索引过旧
1[!] CocoaPods could not find compatible versions for pod "..."
2You have either:
3 * out-of-date source repos which you can update with `pod repo update` or with `pod install --repo-update`.
插件刚升级，要求的原生库版本比本机缓存的索引新，CocoaPods 在本地找不到。
1cd ios
2pod install --repo-update
还不行时检查是否有 Podfile.lock 锁住了旧版本，对报错的那个库执行 pod update 库名。
6. CDN 下载失败
1[!] CDN: trunk URL couldn't be downloaded: https://cdn.cocoapods.org/... Response: ...
也可能是 CDN: trunk Repo update failed。访问 CocoaPods CDN 超时或被中断，属于网络问题，和工程配置无关。
先重试一次。网络一直不通时，在 Podfile 第一行指定镜像源，例如 source 'https://mirrors.tuna.tsinghua.edu.cn/git/CocoaPods/Specs.git'，做法见 CocoaPods 技术栈。CocoaPods trunk 将在 2026 年 12 月 2 日变为只读，已发布的版本仍可安装，详情见 CocoaPods 迁移到 SPM。
7. CocoaPods 版本太旧
1[Xcodeproj] Unable to find compatibility version string for object version `70`.
报错来自 CocoaPods 读取工程文件的组件。Runner.xcodeproj 被新版 Xcode 保存过，工程格式版本（这里是 70，对应 Xcode 16）比本机 CocoaPods 认识的新。团队里有人在 Mac 上用新版 Xcode 打开过工程时最常见。
升级 CocoaPods 到最新版。用 KXBuild 时运行一次 kxbuild doctor，然后 pod --version 确认版本已更新。
8. Swift 版本无法确定
1[!] Unable to determine Swift version for the following pods:
2
3- `xxx` does not specify a Swift version and none of the targets (`Runner`) integrating it have the `SWIFT_VERSION` attribute set. Please contact the author or set the `SWIFT_VERSION` attribute in at least one of the targets that integrate this pod.
老插件的 podspec 没声明 Swift 版本，而 Runner 也没设 SWIFT_VERSION。Objective-C 模板创建的老 Flutter 工程常见。
给 Runner 设一个 Swift 版本，然后重新 pod install。
1kxbuild project add-setting -k SWIFT_VERSION -v 5.0 -t Runner -P .\ios\Runner.xcodeproj
9. 静态库与动态框架冲突
1[!] The 'Pods-Runner' target has transitive dependencies that include statically linked binaries: (...)
Flutter 模板的 Podfile 写了 use_frameworks!，所有 pod 都按动态框架构建，而某个插件依赖的原生库只提供静态库。
有两种改法。一是把插件升级到新版本，很多 SDK 已经改为提供 xcframework。二是在 Podfile 里改成静态链接。
1target 'Runner' do
2 use_frameworks! :linkage => :static
3 flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
4end
另一条相近的报错是 The following Swift pods cannot yet be integrated as static libraries，提示里写了 Swift pod 依赖的库没有定义模块。按提示在 Podfile 里加 use_modular_headers!，或者只给那个依赖加 :modular_headers => true。
10. sandbox 与 Podfile.lock 不一致
1error: The sandbox is not in sync with the Podfile.lock. Run 'pod install' or update your CocoaPods installation.
这条出现在编译阶段的「[CP] Check Pods Manifest.lock」脚本里。拉取代码后 Podfile.lock 变了，本地 Pods 目录还是旧的。在 ios 目录重新 pod install 即可。
编译与签名阶段报错怎么改？
11. 找不到插件模块
1.../ios/Runner/GeneratedPluginRegistrant.m: fatal error: module 'image_picker_ios' not found
Swift 代码里是 no such module 'xxx'。原因几乎总是两个：加了带原生代码的插件后没执行 pod install，或者构建的是 Runner.xcodeproj。
在 ios 目录执行 pod install，之后始终构建 ios\Runner.xcworkspace。
12. Flutter.h 找不到，或 Run Script 阶段报错
1fatal error: 'Flutter/Flutter.h' file not found
另一种表现是在「Run Script」构建阶段报错退出。Flutter 框架和 Dart 代码的编译环境没准备好，常见于刚换了 Flutter 版本、刚拉下工程，或者在 Windows、Linux 上没先体检。
带上工程路径重新运行体检，再构建。
1kxbuild doctor D:\work\myflutterapp
13. 签名证书找不到
1No signing certificate matching "…" found
Flutter 模板的 Runner 没有设置开发团队，换了电脑或换了证书后最容易出现。用 KXBuild 构建时，证书目录里要有对应的 .p12 和描述文件。放入后重试，或用 -D CODE_SIGN_IDENTITY=… -D DEVELOPMENT_TEAM=… 改成目录里已有的证书。描述文件里要包含 Runner 的 Bundle ID 和这台手机的 UDID，详见证书与签名和签名报错与 ipa 安装失败。
14. arm64 架构相关
链接时出现类似「某个库的目标文件是为 iOS 模拟器构建的」「缺少 arm64 架构」的提示。iPhone 真机只需要 arm64，问题一般出在插件自带的预编译库上。
- 插件只带了模拟器或老架构的二进制。升级插件，确认它提供的 xcframework 里有
ios-arm64目录。 - Podfile 里抄来的 EXCLUDED_ARCHS。网上流传的 post_install 片段有时会排除 arm64。检查
EXCLUDED_ARCHS[sdk=iphoneos*]，真机这一项不能含 arm64。Flutter 自己的配置只会在这里排除 armv7。 - 只排除了模拟器 arm64。
EXCLUDED_ARCHS[sdk=iphonesimulator*]只影响模拟器，和真机包无关，不是这次报错的原因。
15. SPM 插件要求更高的 iOS 版本
1Target Integrity (Xcode): The package product 'plugin_name_ios' requires minimum platform version 14.0 for the iOS platform, but this target supports 12.0
这是 Flutter 官方 Swift Package Manager 说明里给出的报错。Flutter 3.44 起默认开启 SPM，支持 SPM 的插件走 Swift Package，不支持的退回 CocoaPods，所以同一个工程可能同时遇到第 4 条和这一条。改法相同，提高 Runner 的部署目标。
Flutter 文档让你接着运行 flutter build ios --config-only 重新生成配置，这条命令只能在 macOS 上运行。在 Windows、Linux 上改为重新运行一次体检。SPM 与 CocoaPods 混用的注意事项见 CocoaPods 迁移到 SPM。
上传时提示第三方插件缺少隐私清单怎么办？
16. ITMS-91061 Missing privacy manifest
编译和安装都正常，上传 App Store Connect 后收到 ITMS-91061 邮件，说某个第三方 SDK 缺少隐私清单。Apple 的常用第三方 SDK 列表里有不少 Flutter 相关的名字，例如 Flutter 本身、path_provider、shared_preferences_ios、image_picker_ios、url_launcher、sqflite、device_info_plus、package_info_plus、connectivity_plus、share_plus、fluttertoast，以及 FirebaseCore 等 Firebase 库。
列表里的 SDK 被新 App 或新增依赖的更新带进来时必须带隐私清单，作为二进制依赖时还要有签名。
改法是升级插件和 Flutter 到带隐私清单的版本，然后重新 pod install、重新构建。你自己的代码用到 UserDefaults 等必需原因 API 时，还要在 App 里加 PrivacyInfo.xcprivacy，见隐私清单怎么写。其他 ITMS 错误码见 ITMS 错误码对照。
在 Windows、Linux 上怎么用 KXBuild 构建 Flutter 工程？
Flutter 官方的 flutter build ios、flutter run 在 iOS 上只能在 macOS 上运行。在 Windows、Linux 上用 KXBuild 时，iOS 端的构建交给 KXBuild，其他 flutter 命令照常用。按下面的顺序做，可以避开上面大部分错误。
| 步骤 | 命令或操作 | 什么时候做 |
|---|---|---|
| 1 | kxbuild doctor <工程目录>，或 KXBuild 视图「···」中的「体检并修复开发环境」 |
第一次打开工程、换 Flutter 版本、加插件、改 pubspec.yaml 版本号之后 |
| 2 | 在 ios 目录 pod install |
工程里有需要 CocoaPods 的插件时，体检之后执行，体检不会替你做 |
| 3 | 按 F5，或 kxbuild build .\ios\Runner.xcworkspace |
有 Pods 时始终用 .xcworkspace |
| 4 | kxbuild build .\ios\Runner.xcworkspace -c Release --export app-store |
出上架用的 ios\build\Runner.ipa |
和在 Mac 上的差别主要有三点。
- 体检代替 Flutter 的 iOS 准备步骤。Mac 上
flutter build ios会顺带生成 iOS 端配置，Windows 上没有这一步，跳过体检会遇到第 1、12 条。 - 加插件后要体检加 pod install 两步。只执行
flutter pub add不够，iOS 端工程还不认识新插件，会报第 11 条。 - 改了原生配置要完整重建。热重载只更新 Dart 代码，改了部署目标、Podfile、Info.plist 后要停止调试，重新按 F5。
完整流程和其他 Flutter iOS 编译错误的排查见 Flutter 技术栈 和 Flutter 在 Windows 上真机调试 iOS。
常见问题
Flutter iOS 最低部署目标应该设成多少？
截至 2026 年 10 月，Flutter 官方支持 iOS 15 及以上，所以至少设为 15.0。用到的插件要求更高时，以插件要求的最高版本为准，Podfile 的 platform 和 Runner 的 IPHONEOS_DEPLOYMENT_TARGET 设成同一个值。
pod install 提示 Generated.xcconfig must exist 怎么办？
先在工程根目录执行 flutter pub get，再到 ios 目录执行 pod install。在 Windows、Linux 上用 KXBuild 时，先带工程路径运行一次体检，再执行 pod install。
报 required a higher minimum deployment target 是哪里的版本太低？
是工程的最低部署目标低于插件的要求。把 ios/Podfile 里的 platform :ios 和 Runner 的部署目标一起提高到插件要求的版本，然后重新 pod install。
加了 Flutter 插件后编译报 module not found 怎么解决？
带原生代码的插件需要先装 pods。依次运行体检和 pod install，然后构建 Runner.xcworkspace，不要构建 Runner.xcodeproj。
pod install 一直卡住或下载失败怎么办？
这是访问 CocoaPods CDN 或 GitHub 的网络问题。先重试，仍然失败就在 Podfile 第一行指定镜像源，再执行 pod install –repo-update。