大多数 Capacitor iOS 问题可以归纳为五类：工具链错误、依赖解析（SPM 或 CocoaPods）、插件编译错误、code 签名问题，以及诸如 “plugin is not implemented” 或 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请查阅 runner 镜像文档以获取准确路径。针对 module-minimum 错误，请将应用的 deployment target 提升至插件要求的最低版本，或使用旧版插件。
ITMS-90725: SDK version issue 上传时
该构建使用的 SDK 比 Apple 目前接受的版本更旧。自 2026 年 4 月 28 日起，上传的构建必须用 Xcode 26 和 iOS 26 SDK 构建。请参阅 Apple 对 Capacitor 应用的 Xcode 26 要求. Capgo 构建 如果不想维护 Mac runner，已经可以在 Xcode 26 上构建。
Swift Package Manager 错误
Missing package product 'CapApp-SPM'
Xcode 未能解析本地包，或者其缓存已过期。
- File > Packages > Reset Package Caches.
- File > Packages > Resolve Package Versions.
- 如果应用是从 CocoaPods 迁移过来的，请检查
CapApp-SPM是否已添加到项目的 软件包依赖项 标签页，并已链接到 App target。
product 'X' required by package 'capapp-spm' target 'CapApp-SPM' not found
插件的 Package.swift 使用的 package 或 product 名称与 Capacitor CLI 根据其 npm 名称生成的结果不匹配。这是插件 bug。请更新插件，或者 打补丁。插件作者可以在以下位置找到命名规则： 将 Capacitor 插件迁移到 SPM.
“部分已安装的 Capacitor 插件与 SPM 不兼容”
此警告在...期间出现 cap sync 意味着至少有一个插件没有 Package.swift。它不会被打包进 App，因此调用它会失败并提示“not implemented”。请升级插件，换成支持 SPM 的插件，或者 暂时先用 CocoaPods.
Package identity 或 target 名称重复
两个插件共享相同的包标识或目标名称（通常是像这样的通用名称 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. 用于 bunx cap open ios。如果工作区已打开且错误仍然存在，请运行 bunx cap sync ios 以重新安装 pods。
CocoaPods could not find compatible versions for pod "X"
两种原因：
- 过时的 spec repo：运行
cd ios/App && pod install --repo-update. - 冲突的 pins：两个插件需要同一 pod 的不兼容版本。错误信息会打印出依赖链。升级带有严格 pin 的插件，对齐版本（对于 Firebase，请确保所有 Firebase 插件使用相同的 SDK 版本），或修补 podspec。
如果仍然失败，请删除 ios/App/Podfile.lock 以及 ios/App/Pods，然后再次同步。这也会升级所有 pod，因此之后请进行测试。
The sandbox is not in sync with the Podfile.lock
运行 bunx cap sync ios。这通常发生在切换分支或安装不完整之后。
Unable to find compatibility version string for object version '70'
你的 project.pbxproj 使用了你的 CocoaPods 版本无法读取的格式。请更新 CocoaPods（brew upgrade cocoapods 或在你的 Gemfile）中提升版本。作为最后手段，备份该文件并降低 objectVersion.
Sandbox: rsync(...) deny(1) file-write-create
Xcode 的用户脚本沙盒会阻止 CocoaPods 框架嵌入脚本。请设置 Build Settings > User Script Sandboxing 改为 否 在 App target 上。
could not find module 'Capacitor' for target 'x86_64-apple-ios-simulator'
模拟器构建正在为 Intel 运行。在 Apple Silicon 上，这通常意味着 Xcode 在 Rosetta 下运行，或使用了旧版 EXCLUDED_ARCHS[sdk=iphonesimulator*] = arm64 该设置是过去变通方案的遗留。请在 Xcode 中本地运行，从 App target 及任何 post_install hook 中移除该设置，然后清理并重新构建。
编译错误
Command PhaseScriptExecution failed with a nonzero exit code
这是一个 wrapper。在 Report navigator 中展开失败的 build phase，查看脚本输出。Capacitor 应用中常见原因：
- Run Script 需要
node，但 Xcode 找不到它，因为 Xcode 不会加载 shell profile，而 Node 是通过 nvm、fnm 或 Volta 安装的。请在脚本中使用node的完整路径，或在脚本顶部 exportPATH。 - 崩溃报告上传脚本（Sentry、Crashlytics）在 CI 中缺少凭据。
- CocoaPods 嵌入脚本被用户脚本沙盒阻止（见上文）。
'X' is only available in iOS 16.0 or newer
某个插件使用了高于部署目标的 API。请在 Xcode 中提高目标版本，如果使用 CocoaPods，请在 Podfile 中（platform :ios, '16.0'）设置，并查看插件 README 中的最低要求。
插件中出现 Swift 6 并发错误
类似这样的消息 Sending 'x' risks causing data races 当插件或 App target 使用 Swift 6 语言模式时会出现。Capacitor 8 尚未正式支持 Swift 6。在插件更新前，请让 App target 继续使用 Swift 5 语言模式。
Code 签名
Signing for "App" requires a development team
打开 App target > Signing & Capabilities 并选择一个 Team。在 CI 中，传入 DEVELOPMENT_TEAM 改为 xcodebuild 或使用签名工具。如果错误指向的是 pod resource bundle 而非 App，请在 Podfile 中禁用 bundle targets 的签名 post_install hook。
Provisioning profile "X" doesn't include the ... entitlement
你添加了 Capability（Push Notifications、Associated Domains、Sign in with Apple）但没有重新生成 profile。请先在 Apple Developer 后台的 App ID 上启用它，然后刷新 profile。我们的 iOS 证书生成器 可帮你不用折腾 Mac keychain 就能创建证书，而 UDID 查询工具 可帮助注册测试设备。
Unable to install "App" 在设备上
在设备上启用开发者模式 (Settings > Privacy & Security > Developer Mode)，信任开发者证书，并确保设备的 UDID 已包含在开发构建的 provisioning profile 中。
运行时错误
"X" plugin is not implemented on ios
JavaScript 端未找到原生实现。请按以下顺序检查：
- 插件已包含在
package.json并且你在安装后运行了bunx cap sync ios。 - 对于 SPM：插件会出现在
ios/App/CapApp-SPM/Package.swift。如果没有，说明它没有Package.swift. - 对于 CocoaPods：插件会出现在 Podfile 的
capacitor_pods代码块中，并且pod install没有打印任何警告。 - 没有两个插件注册相同的 JS 名称（例如两个推送通知插件）。
WKAppBoundDomains不在Info.plist，或者如果存在，limitsNavigationsToAppBoundDomains已设置且localhost已列出。否则 App-bound domains 会拦截插件脚本注入。- 清理 build 文件夹并重新构建。过时的构建会保留旧的插件注册信息。
启动时白屏
先使用 Safari Web Inspector 检查 WebView。大多数白屏问题都是 JavaScript 错误导致的。
- 错误
webDir:capacitor.config.ts指向一个不包含index.html的文件夹。请检查ios/App/App/public. - 构建目标版本过新：你的 bundler 生成了旧版 WebKit 不支持的语法。Capacitor 8 最低要求 iOS 15，因此请将目标设为 iOS 15
safari15或更高版本，并检查你的browserslist. - 绝对资源路径：
base在 bundler 配置中设置为 CDN 或子路径会导致本地加载失败。 - Live reload 无法连接：开发服务器必须监听你的局域网 IP（
--host 0.0.0.0），手机必须处于同一网络，且 App 需要 本地网络 权限（设置 > 隐私与安全性 > 本地网络）。server.url发布构建前从配置中移除。 - Live update bundle 损坏: 如果应用使用 OTA 更新，有问题的 bundle 可能导致黑屏。Capgo 的 updater 会在
notifyAppReady()未及时调用时自动回滚。请参阅 updater 文档.
内容被刘海或 Home Indicator 遮挡
添加 viewport-fit=cover 到你的 viewport meta 标签中，并用 padding 填充 env(safe-area-inset-top) 以及 env(safe-area-inset-bottom). Capacitor 8 的 System Bars 插件可控制两个平台上的状态栏样式和可见性。
键盘遮挡输入框
配置 Keyboard 插件 resize 模式 (native, body, ionic 或 none) 并在真机上测试。模拟器处理键盘的方式不同。
App Store Connect 错误
ITMS-91053: Missing API declaration：你的应用或插件使用了需要声明原因的 API，但缺少隐私清单条目。请添加一个PrivacyInfo.xcprivacy到 App target 中并附上原因，同时更新自带清单的插件。ITMS-90725: SDK version issue：使用 Xcode 26 重新构建。Invalid Bundle. The bundle ... contains disallowed file 'Frameworks'：有 framework 被嵌入到 extension 或其他 framework 中。请检查 嵌入 App 扩展的设置。
错误未列出时如何调试
- Safari Web 检查器 用于排查 JS 错误和网络请求。iOS 16.4+ 上可检查 Debug 构建。Release 构建请设置
ios.webContentsDebuggingEnabled: true暂时。 - Xcode 控制台 查看原生日志，包括 Capacitor 的
⚡️显示每个插件调用的 bridge 消息。 - Console.app 选中设备后查看崩溃和系统日志。
- 隔离问题：创建一个全新的 App，并
bun create @capacitor/app只添加可疑插件，看看错误是否复现。
本指南中介绍的 调试 Capacitor 应用的终极指南 深入了解每种工具。如果根本原因是插件 Bug，那么 patch 版本 通常是在等待发版期间最快的解除阻塞方式。
