ios-android-logs

Capacitor 应用的 iOS 和 Android 日志

选择实际包含所需消息的日志通道，筛选出应用日志，保存到文件，然后交由他人诊断。

适用场景

在以下情况使用：

• 用户询问如何查看、实时跟踪、筛选或保存设备／模拟器日志。
• iOS／Android 上缺少 console.log 输出或 ⚡️ Capacitor 日志。
• 用户需要从设备或模拟器获取崩溃报告（.ips、tombstone、ANR）。
• Logcat 或统一日志过于杂乱；用户只想查看自己的应用或插件日志。
• 日志命令失败或行为异常：--level error 仍显示所有内容、unable to find utility "devicectl"、Error: Unexpected argument 'log'、adb: no devices/emulators found。

请勿使用：

• 解读错误并修复应用 -> debugging-capacitor。
• 生产环境崩溃／ANR 报告（Sentry、Crashlytics、Datadog） -> capacitor-native-observability。
• 通过 MCP 服务流式传输 AI Agent 日志 -> capacitor-mcp。
• CPU／内存分析 -> capacitor-performance。
• UIScene 生命周期迁移 -> capacitor-uiscene-migration。

Capacitor 输出的位置（主要陷阱）

来源	iOS	Android
Capacitor 桥接消息（⚡️ Loading app at ...、⚡️ To Native ->、错误）	仅 stdout（print）	Logcat 标签 Capacitor 和 Capacitor/<Sub>
原生镜像的 JS console.log/warn/error	stdout，格式为 ⚡️ [log] - ...	Logcat 标签 Capacitor/Console，格式为 File: ... - Line N - Msg: ...
完整保真度的 JS 控制台（对象、堆栈跟踪）	Safari Web Inspector	chrome://inspect
使用 os.Logger / NSLog 的插件／应用代码	统一日志（Console.app、log stream）	不适用
使用 android.util.Log / Capacitor Logger 的插件代码	不适用	Logcat
原生崩溃	.ips 崩溃报告	Logcat 中的 FATAL EXCEPTION 和崩溃缓冲区；原生代码崩溃则查看 tombstone

后果：

• 在 iOS 上，Console.app 和 log stream 不会显示 Capacitor 的 ⚡️ 日志或镜像的 JS 控制台内容。请使用 Xcode 控制台、xcrun simctl launch --console-pty 或 xcrun devicectl device process launch --console。
• 镜像行为遵循 loggingBehavior（none | debug | production，默认值为 debug）：除非设为 production，否则 Release 构建不会生成 Capacitor 日志。
• iOS 进程名称是可执行文件名（Capacitor 模板中为 App），而不是显示名称。请使用 process == "App" 进行筛选。

快速命令

# iOS Simulator: Capacitor + JS console (stdout), relaunching the app
xcrun simctl launch --console-pty --terminate-running-process booted com.example.app

# iOS Simulator: unified log for the app (os_log / NSLog / system messages)
xcrun simctl spawn booted log stream --level debug --predicate 'process == "App"'

# iPhone: install + launch with stdout attached (Xcode 15+ devicectl)
xcrun devicectl list devices
xcrun devicectl device process launch --console --terminate-existing --device <id> com.example.app

# iPhone: unified log snapshot of the last 10 minutes
sudo log collect --device-udid <udid> --last 10m --output /tmp/iphone.logarchive
log show /tmp/iphone.logarchive --predicate 'process == "App"' --info --debug

# Android: only this app (re-run after each app restart, PID changes)
adb logcat --pid="$(adb shell pidof -s com.example.app)"

# Android: Capacitor + JS console only
adb logcat -s Capacitor:V Capacitor/Console:V

# Android: crashes only
adb logcat -b crash

操作步骤

1. 确定目标：模拟器／虚拟设备还是实体设备；Debug 还是 Release；消息由哪个层级生成（见上表）。
2. 检查连接状态：xcrun simctl list devices booted、xcrun devicectl list devices（设备必须已解锁、受信任且已开启 Developer Mode）、adb devices -l。
3. 清除日志并重现问题：在 Android 上运行 adb logcat -c；在 iOS 上先启动日志流，再重新启动应用。
4. 尽早筛选：先按进程／PID 筛选，再按子系统／标签筛选，最后按文本筛选。切勿将未经筛选的系统日志粘贴到对话中。
5. 保存：用户需要分享日志时，将日志保存到文件（> app.log、.logarchive、adb bugreport）；在团队外分享前，删除令牌、电子邮件和身份验证标头。
6. 移交：将相关日志行交由 debugging-capacitor 进行根因分析。

错误处理

消息	解决方法
--level error 仍会显示所有消息	log stream --level 只识别 default、info、debug（它设置的是最低级别，而不是最高级别）。使用 --predicate 'messageType == error OR messageType == fault' 筛选错误。
xcrun: error: unable to find utility "devicectl"	当前活动的开发者目录是 Command Line Tools。运行 sudo xcode-select -s /Applications/Xcode.app/Contents/Developer。
Error: Unexpected argument 'log'（devicectl）	devicectl 没有日志流式传输子命令。stdout 使用 --console，统一日志使用 Console.app 或 log collect --device-udid。
log collect 因权限错误而失败	使用 sudo 运行；设备必须已解锁并受信任。
No devices are booted.（simctl）	运行 xcrun simctl boot "<device name>" 或打开 Simulator。
adb: no devices/emulators found / unauthorized	启用 USB 调试，接受 RSA 提示，然后运行 adb kill-server && adb start-server。
adb logcat --pid= 输出所有内容 / 错误	应用未运行，因此 pidof 没有返回任何内容。请先启动应用。
Android 上没有 Capacitor/Console 行	loggingBehavior: 'none'，或使用默认 debug 设置的 Release 构建。
JS 日志有显示，但对象显示为 [object Object]	原生镜像会将对象转换为字符串；结构化输出请使用 WebView 检查器。

验证

• iOS 模拟器：使用 --console-pty 启动，确认出现 ⚡️ Loading app at capacitor://localhost，并且测试用的 console.log('log-check') 显示为 ⚡️ [log] - log-check。
• iOS 设备：同样通过 devicectl device process launch --console 操作。
• Android：adb logcat -s Capacitor/Console:V 会显示 Msg: log-check。
• 统一日志：插件中的 Logger(subsystem: "com.example.app", category: "test").info("log-check") 会通过 --predicate 'subsystem == "com.example.app"' --level info 显示。

参考资料

仅在涉及相应主题时加载参考资料。

文件	加载时机
references/ios-logs.md	统一日志谓词、Console.app、log collect/log show、通过 devicectl/Xcode 获取 iOS 崩溃报告、向插件添加 os.Logger
references/android-logs.md	logcat 缓冲区/格式/过滤器、Android Studio Logcat 查询、ANR、tombstone、bugreport、WebView（chromium）噪声

资源

• https://developer.apple.com/documentation/os/logging
• https://developer.apple.com/documentation/xcode/acquiring-crash-reports-and-diagnostic-logs
• https://developer.android.com/tools/logcat
• https://developer.android.com/studio/debug/logcat
• https://capacitorjs.com/docs/config