Back to Details

debugging-capacitor

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Debugging Capacitor Applications

Capacitor应用调试指南

Complete guide to debugging Capacitor apps on iOS and Android.
iOS和Android平台Capacitor应用完整调试指南。

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
  • 用户报告应用崩溃
  • 用户需要调试WebView/JavaScript
  • 用户需要调试原生代码
  • 用户遇到网络/API问题
  • 用户发现异常行为
  • 用户询问调试方法

Quick Reference: Debugging Tools

快速参考：调试工具

PlatformWebView DebugNative DebugLogs
iOSSafari Web InspectorXcode DebuggerConsole.app
AndroidChrome DevToolsAndroid Studioadb logcat
平台WebView调试原生调试日志工具
iOSSafari Web InspectorXcode DebuggerConsole.app
AndroidChrome DevToolsAndroid Studioadb logcat

WebView Debugging

WebView调试

iOS: Safari Web Inspector

iOS：Safari Web Inspector

  1. Enable on device:
    • Settings > Safari > Advanced > Web Inspector: ON
    • Settings > Safari > Advanced > JavaScript: ON
  2. Enable in Xcode (capacitor.config.ts):
typescript
const config: CapacitorConfig = {
  ios: {
    webContentsDebuggingEnabled: true, // Required for iOS 16.4+
  },
};
  1. Connect Safari:
    • Open Safari on Mac
    • Develop menu > [Device Name] > [App Name]
    • If no Develop menu: Safari > Settings > Advanced > Show Develop menu
  2. Debug:
    • Console: View JavaScript logs
    • Network: Inspect API calls
    • Elements: Inspect DOM
    • Sources: Set breakpoints
  1. 在设备上启用:
    • 设置 > Safari > 高级 > Web检查器：开启
    • 设置 > Safari > 高级 > JavaScript：开启
  2. 在Xcode中启用（capacitor.config.ts）:
typescript
const config: CapacitorConfig = {
  ios: {
    webContentsDebuggingEnabled: true, // Required for iOS 16.4+
  },
};
  1. 连接Safari:
    • 在Mac上打开Safari
    • 开发菜单 > [设备名称] > [应用名称]
    • 若无开发菜单：Safari > 设置 > 高级 > 显示开发菜单
  2. 调试操作:
    • 控制台：查看JavaScript日志
    • 网络：检查API调用
    • 元素：检查DOM
    • 源代码：设置断点

Android: Chrome DevTools

Android：Chrome DevTools

  1. Enable in config (capacitor.config.ts):
typescript
const config: CapacitorConfig = {
  android: {
    webContentsDebuggingEnabled: true,
  },
};
  1. Connect Chrome:
    • Open Chrome on computer
    • Navigate to 
      chrome://inspect
    • Your device/emulator should appear
    • Click "inspect" under your app
  2. Debug features:
    • Console: JavaScript logs
    • Network: API requests
    • Performance: Profiling
    • Application: Storage, cookies
  1. 在配置中启用（capacitor.config.ts）:
typescript
const config: CapacitorConfig = {
  android: {
    webContentsDebuggingEnabled: true,
  },
};
  1. 连接Chrome:
    • 在电脑上打开Chrome
    • 导航至 
      chrome://inspect
    • 你的设备/模拟器会显示在此处
    • 点击应用下方的「inspect」
  2. 调试功能:
    • 控制台：JavaScript日志
    • 网络：API请求
    • 性能：性能分析
    • 应用：存储、Cookie

Remote Debugging with VS Code

使用VS Code进行远程调试

Install "Debugger for Chrome" extension:
json
// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "chrome",
      "request": "attach",
      "name": "Attach to Android WebView",
      "port": 9222,
      "webRoot": "${workspaceFolder}/dist"
    }
  ]
}
安装「Debugger for Chrome」扩展:
json
// .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

iOS：Xcode Debugger

  1. Open in Xcode:
bash
bunx cap open ios
  1. Set breakpoints:
    • Click line number in Swift/Obj-C files
    • Or use 
      breakpoint set --name methodName
      in LLDB
  2. Run with debugger:
    • Product > Run (Cmd + R)
    • Or click Play button
  3. LLDB Console commands:
lldb
undefined
  1. 在Xcode中打开:
bash
bunx cap open ios
  1. 设置断点:
    • 点击Swift/Obj-C文件的行号
    • 或在LLDB中使用 
      breakpoint set --name methodName
  2. 使用调试器运行:
    • 产品 > 运行（Cmd + R）
    • 或点击播放按钮
  3. LLDB控制台命令:
lldb
undefined

Print variable

Print variable

po myVariable
po myVariable

Print object description

Print object description

p myObject
p myObject

Continue execution

Continue execution

continue
continue

Step over

Step over

next
next

Step into

Step into

step
step

Print backtrace

Print backtrace

bt

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

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

Android: Android Studio Debugger

Android：Android Studio Debugger

  1. Open in Android Studio:
bash
bunx cap open android
  1. Attach debugger:
    • Run > Attach Debugger to Android Process
    • Select your app
  2. Set breakpoints:
    • Click line number in Java/Kotlin files
  3. Debug console:
undefined
  1. 在Android Studio中打开:
bash
bunx cap open android
  1. 附加调试器:
    • 运行 > 附加调试器到Android进程
    • 选择你的应用
  2. 设置断点:
    • 点击Java/Kotlin文件的行号
  3. 调试控制台:
undefined

Evaluate expression

Evaluate expression

myVariable
myVariable

Run method

Run method

myObject.toString()

5. **Logcat shortcuts**:
   - View > Tool Windows > Logcat
   - Filter by package: `package:com.yourapp`
myObject.toString()

5. **Logcat快捷操作**:
   - 视图 > 工具窗口 > Logcat
   - 按包名过滤：`package:com.yourapp`

Console Logging

控制台日志

JavaScript Side

JavaScript端

typescript
// 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');
typescript
// 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)

iOS原生端

swift
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)
swift
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)

Android原生端

kotlin
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)
kotlin
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:
bash
undefined
诊断:
bash
undefined

iOS - Check crash logs

iOS - 检查崩溃日志

xcrun simctl spawn booted log stream --level debug | grep -i crash
xcrun simctl spawn booted log stream --level debug | grep -i crash

Android - Check logcat

Android - 检查logcat

adb logcat *:E | grep -i "fatal|crash"

**Common causes**:
1. Missing plugin registration
2. Invalid capacitor.config
3. Missing native dependencies

**Solution checklist**:
- [ ] Run `bunx cap sync`
- [ ] iOS: `cd ios/App && pod install`
- [ ] Check Info.plist permissions
- [ ] Check AndroidManifest.xml permissions
adb logcat *:E | grep -i "fatal|crash"

**常见原因**:
1. 缺少插件注册
2. capacitor.config配置无效
3. 缺少原生依赖

**解决方案清单**:
- [ ] 运行 `bunx cap sync`
- [ ] iOS: `cd ios/App && pod install`
- [ ] 检查Info.plist权限配置
- [ ] 检查AndroidManifest.xml权限配置

Issue: Plugin Method Not Found

问题：未找到插件方法

Error: 
Error: "MyPlugin" plugin is not implemented on ios/android
Diagnosis:
typescript
import { Capacitor } from '@capacitor/core';

// Check if plugin exists
console.log('Plugins:', Capacitor.Plugins);
console.log('MyPlugin available:', !!Capacitor.Plugins.MyPlugin);
Solutions:
  1. Ensure plugin is installed: 
    bun add @capgo/plugin-name
  2. Run sync: 
    bunx cap sync
  3. Check plugin is registered (native code)
错误信息: 
Error: "MyPlugin" plugin is not implemented on ios/android
诊断:
typescript
import { Capacitor } from '@capacitor/core';

// Check if plugin exists
console.log('Plugins:', Capacitor.Plugins);
console.log('MyPlugin available:', !!Capacitor.Plugins.MyPlugin);
解决方案:
  1. 确保已安装插件：
    bun add @capgo/plugin-name
  2. 执行同步：
    bunx cap sync
  3. 检查插件是否已注册（原生代码中）

Issue: Network Requests Failing

问题：网络请求失败

Diagnosis:
typescript
// 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:
  1. iOS ATS blocking HTTP: Add to Info.plist:
xml
<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>
  1. Android cleartext blocked: Add to capacitor.config.ts:
typescript
server: {
  cleartext: true, // Only for development!
}
  1. CORS issues: Use native HTTP:
typescript
import { CapacitorHttp } from '@capacitor/core';

const response = await CapacitorHttp.request({
  method: 'GET',
  url: 'https://api.example.com/data',
});
诊断:
typescript
// 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;
  }
};
常见原因:
  1. iOS ATS拦截HTTP请求: 在Info.plist中添加：
xml
<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>
  1. Android明文请求被阻止: 在capacitor.config.ts中添加：
typescript
server: {
  cleartext: true, // Only for development!
}
  1. CORS问题: 使用原生HTTP请求：
typescript
import { CapacitorHttp } from '@capacitor/core';

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

Issue: Permission Denied

问题：权限被拒绝

Diagnosis:
typescript
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:
xml
<key>NSCameraUsageDescription</key>
<string>We need camera access to scan documents</string>
Android: Check AndroidManifest.xml:
xml
<uses-permission android:name="android.permission.CAMERA" />
诊断:
typescript
import { Permissions } from '@capacitor/core';

// Check permission status
const status = await Permissions.query({ name: 'camera' });
console.log('Camera permission:', status.state);
iOS: 检查Info.plist是否包含使用说明：
xml
<key>NSCameraUsageDescription</key>
<string>We need camera access to scan documents</string>
Android: 检查AndroidManifest.xml：
xml
<uses-permission android:name="android.permission.CAMERA" />

Issue: White Screen on Launch

问题：启动时显示白屏

Diagnosis:
  1. Check WebView console for errors (Safari/Chrome)
  2. Check if 
    dist/
    folder exists
  3. Verify 
    webDir
    in capacitor.config.ts
Solutions:
bash
undefined
诊断:
  1. 检查WebView控制台错误（Safari/Chrome）
  2. 检查
    dist/
    文件夹是否存在
  3. 验证capacitor.config.ts中的
    webDir
    配置
解决方案:
bash
undefined

Rebuild web assets

Rebuild web assets

bun run build
bun run build

Sync to native

Sync to native

bunx cap sync
bunx cap sync

Check config

Check config

cat capacitor.config.ts
undefined
cat capacitor.config.ts
undefined

Issue: Deep Links Not Working

问题：深度链接无法工作

Diagnosis:
typescript
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.
诊断:
typescript
import { App } from '@capacitor/app';

App.addListener('appUrlOpen', (event) => {
  console.log('Deep link:', event.url);
});
iOS: 检查关联域名权限和apple-app-site-association文件。
Android: 检查AndroidManifest.xml中的意图过滤器。

Performance Debugging

性能调试

JavaScript Performance

JavaScript性能

typescript
// 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);
typescript
// 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)

iOS性能调试（Instruments）

  1. Product > Profile (Cmd + I)
  2. Choose template:
    • Time Profiler: CPU usage
    • Allocations: Memory usage
    • Network: Network activity
  1. 产品 > 性能分析（Cmd + I）
  2. 选择模板:
    • Time Profiler：CPU使用率
    • Allocations：内存使用率
    • Network：网络活动

Android Performance (Profiler)

Android性能调试（Profiler）

  1. View > Tool Windows > Profiler
  2. Select:
    • CPU: Method tracing
    • Memory: Heap analysis
    • Network: Request timeline
  1. 视图 > 工具窗口 > Profiler
  2. 选择:
    • CPU：方法追踪
    • Memory：堆分析
    • Network：请求时间线

Memory Debugging

内存调试

JavaScript Memory Leaks

JavaScript内存泄漏

Use Chrome DevTools Memory tab:
  1. Take heap snapshot
  2. Perform action
  3. Take another snapshot
  4. Compare snapshots
使用Chrome DevTools内存面板:
  1. 拍摄堆快照
  2. 执行操作
  3. 再次拍摄堆快照
  4. 对比快照

iOS Memory (Instruments)

iOS内存调试（Instruments）

bash
undefined
bash
undefined

Run with Leaks instrument

Run with Leaks instrument

xcrun instruments -t Leaks -D output.trace YourApp.app
undefined
xcrun instruments -t Leaks -D output.trace YourApp.app
undefined

Android Memory (LeakCanary)

Android内存调试（LeakCanary）

Add to build.gradle:
groovy
debugImplementation 'com.squareup.leakcanary:leakcanary-android:2.12'
在build.gradle中添加:
groovy
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)
调试问题时请检查：
  • 检查WebView控制台（Safari/Chrome DevTools）
  • 检查原生日志（Xcode控制台/Logcat）
  • 验证插件已安装并同步
  • 检查权限配置（Info.plist/AndroidManifest）
  • 在真实设备上测试（而非仅模拟器）
  • 尝试清理构建（
    rm -rf node_modules && bun install
    ）
  • 验证capacitor.config.ts设置
  • 检查版本不匹配问题（Capacitor相关包）

Resources

参考资源