大多数Capacitor iOS问题分为五类：工具链错误，依赖解析（SPM或CocoaPods），插件编译错误，code签名，和运行时问题，如“插件未实现”或空白WebView。从 bunx cap doctor确认您已选择Xcode 26，运行 bunx cap sync ios，并阅读Xcode构建日志中的第一个错误，而不是最后一个。
本指南列出了我们在 Capacitor 8 个项目中最常见的错误，错误的原因以及解决方法。对于 Android，请参见 Capacitor Android 故障排除指南.
快速排除错误清单
在追踪特定错误之前，请运行这些步骤:
bunx cap doctor # Capacitor, CLI and plugin versions should match
node -v # 22 or later for Capacitor 8
xcodebuild -version # 26.x
xcode-select -p # should point to the Xcode you expect
bun run build && bunx cap sync ios- 版本:
@capacitor/core,@capacitor/ios并且@capacitor/cli必须共享相同的主版本。版本不匹配会导致编译和运行时错误。请参见 修复 Capacitor 版本不匹配错误. - 一台 Xcode:如果您有多个 Xcode 版本
xcode-select -p决定了 CLI 使用哪一个版本。使用以下方法修复它sudo xcode-select -s /Applications/Xcode.app. - 哪个包管理器: 如果存在
ios/App/CapApp-SPM如果存在，项目使用 SPM。如果ios/App/Podfile存在，项目使用 CocoaPods。
工具链错误
Xcode 或 SDK 太旧
症状： value of type 'WKWebView' has no member 'isInspectable', Swift 语法错误在 Capacitor, 或 compiling for iOS 15.0, but module 'X' has a minimum deployment target of iOS 16.0.
Capacitor 8 需要 Xcode 26。在 GitHub Actions 中 macos-latest 不总是指向包含最新 Xcode 的图像。将包含 Xcode 26 的图像固定，然后选择它：
- run: sudo xcode-select -s /Applications/Xcode_26.0.app检查运行器图像文档以获取准确路径。对于模块最小错误，请将应用的部署目标提高到插件的最小值，或者使用旧版本的插件。
ITMS-90725: SDK version issue 在上传时
使用一个 SDK 构建的项目，苹果当前接受的版本。自 2026 年 4 月 28 日起，上传必须使用 Xcode 26 和 iOS 26 SDK 构建。请参阅 苹果的 Xcode 26 要求 Capacitor 应用. Capgo 构建 如果您不想维护Mac运行器，Xcode 26就可以直接构建。
如果您不想维护 Mac 运行器，项目已经在 Xcode 26 上构建。
Missing package product 'CapApp-SPM'
Swift 包管理器错误
- Xcode 未能解决本地包，或者其缓存过时。.
- 文件 > 包 > 重置包缓存.
- 文件 > 包 > 解决包版本
CapApp-SPM如果应用从 CocoaPods 迁移，请检查 是否添加到项目的 包依赖项中，并链接到 App 目标。
product 'X' required by package 'capapp-spm' target 'CapApp-SPM' not found
A插件的 Package.swift uses a package or product name that doesn’t match what the Capacitor CLI generated from its npm name. This is a plugin bug. Update the plugin, or 修复它这是一个插件的bug。更新插件，或者 将一个 Capacitor 插件迁移到 SPM.
“部分安装的Capacitor插件与SPM不兼容”
迁移一个__CAPGO_KEEP_0__插件到SPM cap sync “一些已安装的__CAPGO_KEEP_0__插件不兼容SPM” Package.swift这个警告意味着 至少有一个插件没有.
重复的包标识或目标名称
暂时使用CocoaPods Plugin. 自 CLI 8.4 以后，您可以从 Capacitor 配置中修复它：
const config: CapacitorConfig = {
// ...
experimental: {
ios: {
spm: {
packageOptions: {
'@acme/capacitor-foo': { symlink: true },
'@acme/capacitor-bar': { moduleAliases: { Plugin: 'AcmeBarPlugin' } },
},
},
},
},
};symlink 使 CLI 通过符号链接文件夹引用插件，路径唯一。 moduleAliases 重命名冲突的模块以解决依赖项。请将冲突上报到上游。
不要编辑 CapApp-SPM/Package.swift
CLI 会在每次同步时重写它。 本地编辑会消失。 使用配置选项。 experimental.ios.spm CocoaPods 错误
您打开了
No such module 'Capacitor'
而不是 App.xcodeproj 。 使用 App.xcworkspace. Use bunx cap open ios重新安装 Pods。 bunx cap sync ios 重新安装 Pods。
CocoaPods could not find compatible versions for pod "X"
两种原因：
- 过时的 spec 库: run
cd ios/App && pod install --repo-update. - 冲突的 pins: 两个插件需要不兼容的同一 pod 版本。错误打印链。升级带有严格 pin 的插件，调整版本（对于 Firebase，保持所有 Firebase 插件在相同的 SDK 版本），或修复 podspec。
如果它持续失败，请删除 ios/App/Podfile.lock 和 ios/App/Podscontext
The sandbox is not in sync with the Podfile.lock
Run bunx cap sync iosRun
Unable to find compatibility version string for object version '70'
context project.pbxproj 运行brew upgrade cocoapods 或在你的 Gemfile. 作为最后的手段，备份文件并降低 objectVersion.
Sandbox: rsync(...) deny(1) file-write-create
Xcode的用户脚本sandboxing阻止了CocoaPods框架嵌入脚本。设置 构建设置>用户脚本sandboxing 到 No 否
could not find module 'Capacitor' for target 'x86_64-apple-ios-simulator'
在App目标上。 EXCLUDED_ARCHS[sdk=iphonesimulator*] = arm64 模拟器构建正在为英特尔运行。 在Apple Silicon上，这通常意味着Xcode在Rosetta下运行或是过去的工作-around中遗留的设置。 在Xcode下运行，移除App目标和任何hook中的该设置，然后清理并重建。 post_install 编译错误
这是一个包装器。 扩展失败的构建阶段在报告导航器中读取脚本输出。 __CAPGO_KEEP_0__ 应用程序中的常见原因：
Command PhaseScriptExecution failed with a nonzero exit code
这是一个包装器。 在报告导航器中扩展失败的构建阶段，阅读脚本输出。 Capacitor 应用程序中的常见原因：
- A Run Script 需要
node并且 Xcode 无法找到它，因为 Xcode 不会加载你的 shell 配置文件，Node 是使用 nvm、fnm 或 Volta 安装的。使用脚本的完整路径，或者在脚本顶部导出node在脚本中使用完整的路径，或者在脚本顶部导出PATH在脚本顶部导出 - 在 CI 中的崩溃报告上传脚本 (Sentry、Crashlytics) 缺少凭证。
- CocoaPods embed 脚本被用户脚本sandboxing阻塞（见上文）。
'X' is only available in iOS 16.0 or newer
一个插件使用了 API，而这个版本低于你的部署目标。请在 Xcode 中提高目标，在 Podfile 中（如果你使用 CocoaPods）增加目标，并检查插件的 README 文件以获取其最低版本。platform :ios, '16.0'Swift 6 并发错误在插件中
类似于这些错误
出现于插件或你的 App 目标使用 Swift 6 语言模式时。__CAPGO_KEEP_0__ 8 并不正式支持 Swift 6。请将 App 目标保持在 Swift 5 语言模式，直到插件被更新。 Sending 'x' risks causing data races Capacitor 签名
Code 签名
Signing for "App" requires a development team
打开 App目标 > 签名 & 能力 并选择一个团队。在CI中传递 DEVELOPMENT_TEAM 到 xcodebuild 或使用签名工具。如果错误名称一个pod资源包而不是App，请在Podfile中禁用签名目标 post_install 钩子。
Provisioning profile "X" doesn't include the ... entitlement
您添加了一个能力（推送通知、关联域名、使用Apple登录）而没有重新生成配置文件。启用它在Apple Developer门户中的App ID，然后刷新配置文件。我们的 iOS证书生成器 帮助创建证书而不需要Mac钥匙串舞蹈， UDID查找器 帮助注册测试设备。
Unable to install "App" 在设备上
在设备上启用开发者模式（设置 >隐私和安全 >开发者模式），信任开发者证书，并确保设备的UDID已添加到开发者配置文件中。
运行时错误
"X" plugin is not implemented on ios
JavaScript侧未找到本机实现。检查以下顺序:
- 插件位于
package.json并且您已运行bunx cap sync ios在安装它之后。 - 对于SPM：插件在
ios/App/CapApp-SPM/Package.swift中显示。如果没有，则没有Package.swift. - 对于CocoaPods：插件在
capacitor_podsPodfile的pod install块中，并且 - 打印了警告信息。没有警告信息打印。
WKAppBoundDomains不在Info.plist或如果是limitsNavigationsToAppBoundDomainsis set andlocalhost在 App-bound domains 列表中列出。应用绑定域阻止插件脚本注入。- 清理构建文件夹并重建。过期构建会保留旧插件注册。
白屏启动
使用 Safari Web Inspector 检查 WebView 首先。多数空白屏幕都是 JavaScript 错误。
- Wrong
webDir:capacitor.config.tspoints to a folder that doesn’t containindex.html. Checkios/App/App/public. - 目标构建目标过于新版iOS 15 是最低要求的版本，Capacitor 8 需要 iOS 15 或更高版本。
safari15或更高版本的Vite/esbuild并检查您的browserslist. - 绝对资产路径: a
baseLive reload不可达 - : 开发服务器必须监听您的局域网IP（），手机必须在同一网络上，且应用需要
--host 0.0.0.0本地网络 权限（设置>隐私和安全>本地网络）。在发布构建之前，请从配置中移除 __CAPGO_KEEP_0__server.url捆绑包损坏 - : 如果应用使用OTA更新，一个坏的捆绑包会导致屏幕变成白色。Live update的更新器在发生错误时会自动回滚Capgo
notifyAppReady()没有被及时调用。参见 更新器文档.
内容在 notch 或 home 指示器下
添加 viewport-fit=cover 到您的视口元标签并用 env(safe-area-inset-top) 和 env(safe-area-inset-bottom). Capacitor 8 的系统栏插件控制了状态栏的样式和可见性，适用于两种平台。
键盘遮挡输入
配置 键盘插件 resize 模式（native, body, ionic 或 none）并在真机上测试。模拟器处理键盘有所不同。
App Store Connect 错误
ITMS-91053: Missing API declaration:您的应用或插件使用了一个需要隐私原因的API但没有隐私清单条目。添加一个PrivacyInfo.xcprivacy到 App 目标中，包含原因，并更新那些自行提供清单的插件。ITMS-90725: SDK version issue:使用 Xcode 26 重建。Invalid Bundle. The bundle ... contains disallowed file 'Frameworks':一个框架被嵌入到扩展或另一个框架中。检查 嵌入 设置
如何调试当错误未列出时
- Safari Web Inspector 用于 JS 错误和网络调用调试。调试版在 iOS 16.4+ 上可用。对于发布版，请设置
ios.webContentsDebuggingEnabled: true暂时 - Xcode控制台 用于本机日志的，包括Capacitor的
⚡️桥接消息，显示每个插件调用。 - 控制台 选择设备并打开崩溃和系统日志。
- 隔离:创建一个新的应用程序，
bun create @capacitor/app只添加可疑的插件，
并查看错误是否重现。 调试Capacitor应用程序的终极指南 更深入地介绍了每个工具。如果根源是插件错误， 一个修复 通常是最快的解锁方式，等待发布期间。
