Capacitor iOS 故障排除：常见错误及解决方案

大多数 Capacitor iOS 问题可归纳为五类：工具链错误、依赖解析（SPM 或 CocoaPods）、插件编译错误、code 签名问题，以及“插件未实现”或 WebView 白屏等运行时问题。首先 bunx cap doctor，确认已选择 Xcode 26，然后运行 bunx cap sync ios，并且请查看 Xcode build log 中的第一个错误，而不是最后一个。

本指南列出了我们在 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 image 文档以获取准确路径。针对 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 未能解析本地 package，或者其缓存已过期。

1. File > Packages > Reset Package Caches.
2. File > Packages > Resolve Package Versions.
3. 如果应用是从 CocoaPods 迁移过来的，请检查 CapApp-SPM 是否已添加到项目的 Package Dependencies 中 标签页并已链接到 App target。

product 'X' required by package 'capapp-spm' target 'CapApp-SPM' not found

插件的 Package.swift 使用的包名或产品名与 Capacitor CLI 根据其 npm 名称生成的结果不匹配。这是插件 bug。请更新插件，或者 打补丁。插件作者可以在以下位置找到命名规则： 将 Capacitor 插件迁移到 SPM.

“部分已安装的 Capacitor 插件与 SPM 不兼容”

在……期间出现此警告 cap sync 意味着至少有一个插件缺少 Package.swift。它不会被打包进 App，因此调用它会失败并提示“not implemented”。请升级插件、换成支持 SPM 的插件，或者 暂时使用 CocoaPods.

包标识符或 target 名称重复

两个插件共用了同一个 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 通过具有唯一路径的 symlink 文件夹引用该插件。 moduleAliases 为该依赖项重命名冲突的 module。同时请向 upstream 报告该冲突。

不要编辑 CapApp-SPM/Package.swift

CLI 会在每次 sync 时重写它。本地修改会丢失。请改用 experimental.ios.spm 配置选项。

CocoaPods 错误

No such module 'Capacitor'

你打开了 App.xcodeproj 而不是 App.xcworkspace。请使用 bunx cap open ios。如果 workspace 已打开且错误仍然存在，请运行 bunx cap sync ios 重新安装 pods。

CocoaPods could not find compatible versions for pod "X"

两个原因：

1. Spec 仓库过时: 运行 cd ios/App && pod install --repo-update.
2. 版本冲突: 两个插件需要不兼容的同名 pod 版本。错误信息会打印出依赖链。请升级带有严格版本限制的插件、统一版本（例如 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 的 User Script Sandboxing 会阻止 CocoaPods framework embed 脚本。请将 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 中移除该设置，然后 clean 并重新构建。

编译错误

Command PhaseScriptExecution failed with a nonzero exit code

这只是一个封装。请在 Report 导航栏中展开失败的 build phase 并查看脚本输出。Capacitor 应用中常见的原因为：

• Run Script 需要 node 但 Xcode 找不到它，因为 Xcode 不会加载你的 shell profile，且 Node 是通过 nvm、fnm 或 Volta 安装的。请在脚本中使用 node 的全路径，或者在脚本顶部 PATH 。
• 崩溃报告上传脚本（Sentry、Crashlytics）在 CI 环境中缺少凭据。
• CocoaPods embed 脚本被 user script sandboxing 拦截（见上文）。

'X' is only available in iOS 16.0 or newer

某个插件使用了高于你 deployment target 的 API。请在 Xcode 中调高 target，如果你使用 CocoaPods，请在 Podfile 中修改 ("platform :ios, '16.0'")，并检查该插件 README 中的最低版本要求。

插件中出现了 Swift 6 并发错误

当插件或你的 App target 使用 Swift 6 语言模式时，会出现如下消息： Sending 'x' risks causing data races show up when a plugin or your app target uses Swift 6 language mode. Capacitor 8 doesn’t officially support Swift 6. Keep the App target on Swift 5 language mode until the plugin is updated.

Code 签名

Signing for "App" requires a development team

打开 App target > Signing & Capabilities 并选择一个 Team。在 CI 环境中，请传递 DEVELOPMENT_TEAM 至 xcodebuild 或使用签名工具。如果错误指向的是 pod resource bundle 而非 App，请在 Podfile 中禁用 bundle targets 的 signing post_install hook。

Provisioning profile "X" doesn't include the ... entitlement

你添加了新的 capability（如 Push Notifications, Associated Domains, Sign in with Apple）但未重新生成 profile。请先在 Apple Developer portal 的 App ID 中启用它，然后刷新 profiles。我们的 iOS 证书生成器 可以帮你无需通过 Mac keychain 繁琐操作即可创建证书，而 UDID 查询工具 可以帮助注册测试设备。

Unable to install "App" 在设备上

在设备上启用开发者模式 (Settings > Privacy & Security > Developer Mode)，信任开发者证书，并确保设备的 UDID 已包含在开发构建的 provisioning profile 中。

运行时错误

"X" plugin is not implemented on ios

JavaScript 端未找到原生实现。请按以下顺序检查：

1. 插件已包含在 package.json 并且你在安装后运行了 bunx cap sync ios 。
2. 对于 SPM：插件已出现在 ios/App/CapApp-SPM/Package.swift。如果没有，则说明它没有 Package.swift.
3. 对于 CocoaPods：插件已出现在 Podfile 的 capacitor_pods 代码块中，并且 pod install 没有打印任何警告。
4. 确保没有两个插件注册了相同的 JS 名称（例如两个推送通知插件）。
5. WKAppBoundDomains 不在 Info.plist，或者如果是， limitsNavigationsToAppBoundDomains 已设置且 localhost 已列出。否则 App-bound domains 会拦截插件脚本注入。
6. 清理 build 文件夹并重新构建。过时的 build 会保留旧的插件注册信息。

启动时出现白屏

先使用 Safari Web Inspector 检查 WebView。大多数白屏都是 JavaScript 错误导致的。

• 错误的 webDir: capacitor.config.ts 指向了一个不包含 index.html的文件夹。请检查 ios/App/App/public.
• Build target 版本过高: 你的 bundler 生成了旧版 WebKit 不支持的语法。iOS 15 是 Capacitor 8 的最低要求，因此请将目标设为 iOS 15 safari15 或更高版本（Vite/esbuild），并检查你的 browserslist.
• 绝对资源路径: 将 base bundler 配置中的 base 设为 CDN 或子路径会导致本地加载失败。
• Live reload 无法连接: 开发服务器必须监听你的局域网 IP (--host 0.0.0.0），手机必须连接同一网络，且 App 需要 本地网络 权限（设置 > 隐私与安全性 > 本地网络）。 server.url 在 release 构建前从配置中移除。
• Live update bundle 损坏: 如果应用使用了 OTA 更新，错误的 bundle 可能会导致黑屏。当 Capgo 的更新器未能在规定时间内调用时，会自动回滚。 notifyAppReady() 未能及时调用。请参阅 更新器文档.

内容被刘海屏或底部指示条遮挡

添加 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 内部。请检查 Embed 的 App extension 设置。

如果错误未在列表中，该如何调试

1. Safari Web Inspector 用于调试 JS 错误和网络请求。iOS 16.4+ 支持调试 Debug 版本。对于 Release 版本，请设置 ios.webContentsDebuggingEnabled: true 临时解决。
2. Xcode 控制台 查看原生日志，包括 Capacitor 的 ⚡️ 显示每个插件调用的桥接消息。
3. Console.app 选择对应设备以查看崩溃和系统日志。
4. 隔离问题: 创建一个全新的 App，并 bun create @capacitor/app，仅添加可疑插件，观察错误是否复现。

该 Capacitor App 调试终极指南 将深入介绍每种工具。如果根本原因是插件 Bug，则需 patch 通常是等待新版本发布时最快的解决办法。