Capacitor应用调试指南：iOS/Android WebView与原生代码调试完整教程

debugging-capacitor by cap-go/capgo-skills

96 周安装量

20 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/cap-go/capgo-skills --skill debugging-capacitor

移动应用 JavaScript 框架调试

🇨🇳中文介绍

调试 Capacitor 应用程序

在 iOS 和 Android 上调试 Capacitor 应用程序的完整指南。

何时使用此技能

用户报告应用程序崩溃
用户需要调试 WebView/JavaScript
用户需要调试原生代码
用户遇到网络/API 问题
用户看到意外行为
用户询问如何调试

快速参考：调试工具

平台	WebView 调试	原生调试	日志
iOS	Safari Web 检查器	Xcode 调试器	Console.app
Android	Chrome DevTools	Android Studio 调试器	adb logcat

WebView 调试

iOS：Safari Web 检查器

在设备上启用 ：
- 设置 > Safari > 高级 > Web 检查器：开启
- 设置 > Safari > 高级 > JavaScript：开启
在 Xcode 中启用 (capacitor.config.ts)：

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

Android：Chrome DevTools

在配置中启用 (capacitor.config.ts)：

const config: CapacitorConfig = {

  android: {
    webContentsDebuggingEnabled: true,
  },
};

2. 连接 Chrome ：

 * 在电脑上打开 Chrome
 * 导航到 `chrome://inspect`
 * 您的设备/模拟器应该会出现
 * 在您的应用程序下点击“inspect”

3. 调试功能 ：

 * 控制台：JavaScript 日志
 * 网络：API 请求
 * 性能：性能分析
 * 应用程序：存储、Cookie

使用 VS Code 进行远程调试

安装 "Debugger for Chrome" 扩展：

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "chrome",
      "request": "attach",
      "name": "附加到 Android WebView",
      "port": 9222,
      "webRoot": "${workspaceFolder}/dist"
    }
  ]
}

iOS：Xcode 调试器

在 Xcode 中打开 ：

设置断点 ：
- 在 Swift/Obj-C 文件中点击行号
- 或者在 LLDB 中使用 breakpoint set --name methodName
使用调试器运行 ：
- 产品 > 运行 (Cmd + R)
- 或者点击播放按钮
LLDB 控制台命令 ：

po myVariable

# 打印对象描述
p myObject

# 继续执行
continue

# 单步跳过
next

# 单步进入
step

# 打印回溯
bt

5. 查看崩溃日志 ： * 窗口 > 设备和模拟器 * 选择设备 > 查看设备日志

Android：Android Studio 调试器

在 Android Studio 中打开 ：

bunx cap open android

附加调试器 ：
- 运行 > 将调试器附加到 Android 进程
- 选择您的应用程序
设置断点 ：
- 在 Java/Kotlin 文件中点击行号
调试控制台 ：

myVariable

# 运行方法
myObject.toString()

5. Logcat 快捷方式 ： * 视图 > 工具窗口 > Logcat * 按包名过滤：package:com.yourapp

控制台日志记录

// 基本日志记录
console.log('调试信息：', data);
console.warn('警告：', issue);
console.error('错误：', error);

// 分组日志
console.group('API 调用');
console.log('URL：', url);
console.log('响应：', response);
console.groupEnd();

// 表格格式
console.table(arrayOfObjects);

// 计时
console.time('operation');
// ... 操作
console.timeEnd('operation');

import os.log

let logger = Logger(subsystem: "com.yourapp", category: "MyPlugin")

// 日志级别
logger.debug("调试消息")
logger.info("信息消息")
logger.warning("警告消息")
logger.error("错误消息")

// 带数据
logger.info("用户 ID： \(userId)")

// 传统 NSLog (在 Console.app 中显示)
NSLog("传统日志： %@", message)

import android.util.Log

// 日志级别
Log.v("MyPlugin", "详细消息")
Log.d("MyPlugin", "调试消息")
Log.i("MyPlugin", "信息消息")
Log.w("MyPlugin", "警告消息")
Log.e("MyPlugin", "错误消息")

// 带异常
Log.e("MyPlugin", "发生错误", exception)

常见问题及解决方案

问题：应用程序启动时崩溃

# iOS - 检查崩溃日志
xcrun simctl spawn booted log stream --level debug | grep -i crash

# Android - 检查 logcat
adb logcat *:E | grep -i "fatal\|crash"

常见原因 ：

缺少插件注册
无效的 capacitor.config
缺少原生依赖项

解决方案检查清单 ：

运行 bunx cap sync
iOS：cd ios/App && pod install
检查 Info.plist 权限
检查 AndroidManifest.xml 权限

问题：找不到插件方法

错误：Error: "MyPlugin" plugin is not implemented on ios/android

import { Capacitor } from '@capacitor/core';

// 检查插件是否存在
console.log('插件：', Capacitor.Plugins);
console.log('MyPlugin 可用：', !!Capacitor.Plugins.MyPlugin);

解决方案 ：

确保插件已安装：bun add @capgo/plugin-name
运行同步：bunx cap sync
检查插件是否已注册（原生代码）

问题：网络请求失败

// 添加请求拦截器
const originalFetch = window.fetch;
window.fetch = async (...args) => {
  console.log('Fetch：', args[0]);
  try {
    const response = await originalFetch(...args);
    console.log('响应状态：', response.status);
    return response;
  } catch (error) {
    console.error('Fetch 错误：', error);
    throw error;
  }
};

常见原因 ：

iOS ATS 阻止 HTTP ：添加到 Info.plist：

<key>NSAppTransportSecurity</key>

<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

2. Android 明文传输被阻止 ：添加到 capacitor.config.ts：

server: {
  cleartext: true, // 仅用于开发！
}

3. CORS 问题 ：使用原生 HTTP：

import { CapacitorHttp } from '@capacitor/core';

const response = await CapacitorHttp.request({
  method: 'GET',
  url: 'https://api.example.com/data',
});

问题：权限被拒绝

import { Permissions } from '@capacitor/core';

// 检查权限状态
const status = await Permissions.query({ name: 'camera' });
console.log('相机权限：', status.state);

iOS ：检查 Info.plist 是否有使用说明：

<key>NSCameraUsageDescription</key>
<string>我们需要相机权限来扫描文档</string>

Android ：检查 AndroidManifest.xml：

<uses-permission android:name="android.permission.CAMERA" />

问题：启动时白屏

检查 WebView 控制台是否有错误 (Safari/Chrome)
检查 dist/ 文件夹是否存在
验证 capacitor.config.ts 中的 webDir

解决方案 ：

# 重新构建 Web 资源
bun run build

# 同步到原生端
bunx cap sync

# 检查配置
cat capacitor.config.ts

问题：深度链接不工作

import { App } from '@capacitor/app';

App.addListener('appUrlOpen', (event) => {
  console.log('深度链接：', event.url);
});

iOS ：检查关联域权利和 apple-app-site-association 文件。

Android ：检查 AndroidManifest.xml 中的意图过滤器。

// 标记性能
performance.mark('start');
// ... 操作
performance.mark('end');
performance.measure('operation', 'start', 'end');

const measures = performance.getEntriesByName('operation');
console.log('持续时间：', measures[0].duration);

iOS 性能 (Instruments)

产品 > 配置文件 (Cmd + I)
选择模板：
- 时间分析器：CPU 使用率
- 分配：内存使用情况
- 网络：网络活动

Android 性能 (Profiler)

视图 > 工具窗口 > Profiler
选择：
- CPU：方法追踪
- 内存：堆分析
- 网络：请求时间线

JavaScript 内存泄漏

使用 Chrome DevTools 内存标签页：

拍摄堆快照
执行操作
拍摄另一个快照
比较快照

iOS 内存 (Instruments)

# 使用 Leaks 工具运行
xcrun instruments -t Leaks -D output.trace YourApp.app

Android 内存 (LeakCanary)

添加到 build.gradle：

debugImplementation 'com.squareup.leakcanary:leakcanary-android:2.12'

检查 WebView 控制台 (Safari/Chrome DevTools)
检查原生日志 (Xcode Console/Logcat)
验证插件是否已安装和同步
检查权限 (Info.plist/AndroidManifest)
在真实设备上测试（不仅仅是模拟器）
尝试清理构建 (rm -rf node_modules && bun install)
验证 capacitor.config.ts 设置
检查版本不匹配 (capacitor 包)

🇺🇸English

Debugging Capacitor Applications

Complete guide to debugging Capacitor apps on iOS and Android.

When to Use This Skill

User reports app crashes
User needs to debug WebView/JavaScript
User needs to debug native code
User has network/API issues
User sees unexpected behavior
User asks how to debug

Quick Reference: Debugging Tools

Platform	WebView Debug	Native Debug	Logs
iOS	Safari Web Inspector	Xcode Debugger	Console.app
Android	Chrome DevTools	Android Studio	adb logcat

WebView Debugging

iOS: Safari Web Inspector

Enable on device :
- Settings > Safari > Advanced > Web Inspector: ON
- Settings > Safari > Advanced > JavaScript: ON
Enable in Xcode (capacitor.config.ts):

const config: CapacitorConfig = {

  ios: {
    webContentsDebuggingEnabled: true, // Required for iOS 16.4+
  },
};

3. Connect Safari :

 * Open Safari on Mac
 * Develop menu > [Device Name] > [App Name]
 * If no Develop menu: Safari > Settings > Advanced > Show Develop menu

4. Debug :

 * Console: View JavaScript logs
 * Network: Inspect API calls
 * Elements: Inspect DOM
 * Sources: Set breakpoints

Android: Chrome DevTools

Enable in config (capacitor.config.ts):

const config: CapacitorConfig = {

  android: {
    webContentsDebuggingEnabled: true,
  },
};

2. Connect Chrome :

 * Open Chrome on computer
 * Navigate to `chrome://inspect`
 * Your device/emulator should appear
 * Click "inspect" under your app

3. Debug features :

 * Console: JavaScript logs
 * Network: API requests
 * Performance: Profiling
 * Application: Storage, cookies

Remote Debugging with VS Code

Install "Debugger for Chrome" extension:

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "chrome",
      "request": "attach",
      "name": "Attach to Android WebView",
      "port": 9222,
      "webRoot": "${workspaceFolder}/dist"
    }
  ]
}

Native Debugging

iOS: Xcode Debugger

Open in Xcode :

bunx cap open ios

Set breakpoints :
- Click line number in Swift/Obj-C files
- Or use breakpoint set --name methodName in LLDB
Run with debugger :
- Product > Run (Cmd + R)
- Or click Play button
LLDB Console commands :

# Print variable

po myVariable

# Print object description
p myObject

# Continue execution
continue

# Step over
next

# Step into
step

# Print backtrace
bt

5. View crash logs : * Window > Devices and Simulators * Select device > View Device Logs

Android: Android Studio Debugger

Open in Android Studio :

bunx cap open android

Attach debugger :
- Run > Attach Debugger to Android Process
- Select your app
Set breakpoints :
- Click line number in Java/Kotlin files
Debug console :

# Evaluate expression

myVariable

# Run method
myObject.toString()

5. Logcat shortcuts : * View > Tool Windows > Logcat * Filter by package: package:com.yourapp

Console Logging

JavaScript Side

// Basic logging
console.log('Debug info:', data);
console.warn('Warning:', issue);
console.error('Error:', error);

// Grouped logs
console.group('API Call');
console.log('URL:', url);
console.log('Response:', response);
console.groupEnd();

// Table format
console.table(arrayOfObjects);

// Timing
console.time('operation');
// ... operation
console.timeEnd('operation');

Native Side (iOS)

import os.log

let logger = Logger(subsystem: "com.yourapp", category: "MyPlugin")

// Log levels
logger.debug("Debug message")
logger.info("Info message")
logger.warning("Warning message")
logger.error("Error message")

// With data
logger.info("User ID: \(userId)")

// Legacy NSLog (shows in Console.app)
NSLog("Legacy log: %@", message)

Native Side (Android)

import android.util.Log

// Log levels
Log.v("MyPlugin", "Verbose message")
Log.d("MyPlugin", "Debug message")
Log.i("MyPlugin", "Info message")
Log.w("MyPlugin", "Warning message")
Log.e("MyPlugin", "Error message")

// With exception
Log.e("MyPlugin", "Error occurred", exception)

Common Issues and Solutions

Issue: App Crashes on Startup

Diagnosis :

# iOS - Check crash logs
xcrun simctl spawn booted log stream --level debug | grep -i crash

# Android - Check logcat
adb logcat *:E | grep -i "fatal\|crash"

Common causes :

Missing plugin registration
Invalid capacitor.config
Missing native dependencies

Solution checklist :

Run bunx cap sync
iOS: cd ios/App && pod install
Check Info.plist permissions
Check AndroidManifest.xml permissions

Issue: Plugin Method Not Found

Error : Error: "MyPlugin" plugin is not implemented on ios/android

Diagnosis :

import { Capacitor } from '@capacitor/core';

// Check if plugin exists
console.log('Plugins:', Capacitor.Plugins);
console.log('MyPlugin available:', !!Capacitor.Plugins.MyPlugin);

Solutions :

Ensure plugin is installed: bun add @capgo/plugin-name
Run sync: bunx cap sync
Check plugin is registered (native code)

Issue: Network Requests Failing

Diagnosis :

// Add request interceptor
const originalFetch = window.fetch;
window.fetch = async (...args) => {
  console.log('Fetch:', args[0]);
  try {
    const response = await originalFetch(...args);
    console.log('Response status:', response.status);
    return response;
  } catch (error) {
    console.error('Fetch error:', error);
    throw error;
  }
};

Common causes :

iOS ATS blocking HTTP : Add to Info.plist:

<key>NSAppTransportSecurity</key>

<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

2. Android cleartext blocked : Add to capacitor.config.ts:

server: {
  cleartext: true, // Only for development!
}

3. CORS issues : Use native HTTP:

import { CapacitorHttp } from '@capacitor/core';

const response = await CapacitorHttp.request({
  method: 'GET',
  url: 'https://api.example.com/data',
});

Issue: Permission Denied

Diagnosis :

import { Permissions } from '@capacitor/core';

// Check permission status
const status = await Permissions.query({ name: 'camera' });
console.log('Camera permission:', status.state);

iOS : Check Info.plist has usage descriptions:

<key>NSCameraUsageDescription</key>
<string>We need camera access to scan documents</string>

Android : Check AndroidManifest.xml:

<uses-permission android:name="android.permission.CAMERA" />

Issue: White Screen on Launch

Diagnosis :

Check WebView console for errors (Safari/Chrome)
Check if dist/ folder exists
Verify webDir in capacitor.config.ts

Solutions :

# Rebuild web assets
bun run build

# Sync to native
bunx cap sync

# Check config
cat capacitor.config.ts

Issue: Deep Links Not Working

Diagnosis :

import { App } from '@capacitor/app';

App.addListener('appUrlOpen', (event) => {
  console.log('Deep link:', event.url);
});

iOS : Check Associated Domains entitlement and apple-app-site-association file.

Android : Check intent filters in AndroidManifest.xml.

Performance Debugging

JavaScript Performance

// Mark performance
performance.mark('start');
// ... operation
performance.mark('end');
performance.measure('operation', 'start', 'end');

const measures = performance.getEntriesByName('operation');
console.log('Duration:', measures[0].duration);

iOS Performance (Instruments)

Product > Profile (Cmd + I)
Choose template:
- Time Profiler: CPU usage
- Allocations: Memory usage
- Network: Network activity

Android Performance (Profiler)

View > Tool Windows > Profiler
Select:
- CPU: Method tracing
- Memory: Heap analysis
- Network: Request timeline

Memory Debugging

JavaScript Memory Leaks

Use Chrome DevTools Memory tab:

Take heap snapshot
Perform action
Take another snapshot
Compare snapshots

iOS Memory (Instruments)

# Run with Leaks instrument
xcrun instruments -t Leaks -D output.trace YourApp.app

Android Memory (LeakCanary)

Add to build.gradle:

debugImplementation 'com.squareup.leakcanary:leakcanary-android:2.12'

Debugging Checklist

When debugging issues:

Check WebView console (Safari/Chrome DevTools)
Check native logs (Xcode Console/Logcat)
Verify plugin is installed and synced
Check permissions (Info.plist/AndroidManifest)
Test on real device (not just simulator)
Try clean build (rm -rf node_modules && bun install)
Verify capacitor.config.ts settings
Check for version mismatches (capacitor packages)

Resources

Capacitor Debugging Guide: https://capacitorjs.com/docs/guides/debugging
Safari Web Inspector: https://webkit.org/web-inspector
Chrome DevTools: https://developer.chrome.com/docs/devtools
Xcode Debugging: https://developer.apple.com/documentation/xcode/debugging
Android Studio Debugging: https://developer.android.com/studio/debug

Weekly Installs

Repository

cap-go/capgo-skills

GitHub Stars

First Seen

Feb 6, 2026

Security Audits

Gen Agent Trust HubFail SocketPass SnykPass

Installed on

gemini-cli67

opencode65

github-copilot63

codex63

kimi-cli61

amp61

Genkit JS 开发指南：AI 应用构建、错误排查与最佳实践

6,100 周安装

Capacitor应用调试指南：iOS/Android WebView与原生代码调试完整教程

🇨🇳中文介绍

调试 Capacitor 应用程序

何时使用此技能

快速参考：调试工具

WebView 调试

iOS：Safari Web 检查器

相关 Skills

Android：Chrome DevTools

使用 VS Code 进行远程调试

原生调试

iOS：Xcode 调试器

Android：Android Studio 调试器

控制台日志记录

JavaScript 端

原生端 (iOS)

原生端 (Android)

常见问题及解决方案

问题：应用程序启动时崩溃

问题：找不到插件方法

问题：网络请求失败

问题：权限被拒绝

问题：启动时白屏

问题：深度链接不工作

性能调试

JavaScript 性能

iOS 性能 (Instruments)

Android 性能 (Profiler)

内存调试

JavaScript 内存泄漏

iOS 内存 (Instruments)

Android 内存 (LeakCanary)

调试检查清单

资源

🇺🇸English

Debugging Capacitor Applications

When to Use This Skill

Quick Reference: Debugging Tools

WebView Debugging

iOS: Safari Web Inspector

Android: Chrome DevTools

Remote Debugging with VS Code

Native Debugging

iOS: Xcode Debugger

Android: Android Studio Debugger

Console Logging

JavaScript Side

Native Side (iOS)

Native Side (Android)

Common Issues and Solutions

Issue: App Crashes on Startup

Issue: Plugin Method Not Found

Issue: Network Requests Failing

Issue: Permission Denied

Issue: White Screen on Launch

Issue: Deep Links Not Working

Performance Debugging

JavaScript Performance

iOS Performance (Instruments)

Android Performance (Profiler)

Memory Debugging

JavaScript Memory Leaks

iOS Memory (Instruments)

Android Memory (LeakCanary)

Debugging Checklist

Resources

最新 Skills