Flutter OH平台 DFX 问题定位导航

Flutter OHOS 平台 DFX 问题定位导航面向使用 Flutter OHOS SDK 的应用开发者包括 Flutter 初学者遇到问题时请从下方「故障速查」入口开始0. 新手必读基础概念在开始排查问题之前先了解几个基础概念。这些概念在后续文档中会反复出现。0.1 什么是 DFXDFX 是 “Design for X” 的缩写在这里特指可测试性/可诊断性设计。简单来说就是 Flutter 引擎内置了一套自我监控机制当应用出现崩溃、卡死、卡顿、内存泄漏等问题时引擎会自动记录日志和事件帮助开发者定位问题原因。0.2 什么是 HiLog / HiAppEvent / HiTrace这是 OHOS 系统提供的三套诊断工具你可以把它们理解为工具通俗理解类比HiLog系统日志类似print()输出就像浏览器的 ConsoleHiAppEvent结构化事件上报比日志更有条理就像 Crashlytics 的崩溃报告HiTrace性能追踪记录每一帧的耗时就像 Chrome DevTools 的 Performance新手提示排查问题时第一步永远是抓取 HiLog 日志见 §2日志里包含了大部分问题的线索。0.3 什么是 hdchdc是 OHOS Device Connector 的缩写类似于 Android 的adb。它用于在电脑和 OHOS 设备之间传输文件、执行命令。# 查看已连接的设备hdc list targets# 在设备上执行命令hdc shell命令# 从设备拉取文件到电脑hdcfilerecv设备路径电脑路径0.4 Flutter 的三个线程是什么Flutter 应用运行时有三个关键线程理解它们有助于排查卡死和卡顿问题线程通俗理解出问题时的表现UI 线程负责运行你的 Dart 代码、构建 Widget 树界面完全冻结触摸无响应Raster 线程光栅化线程负责把 Widget 树绘制成像素交给 GPU界面不更新但触摸可能有响应Platform 线程负责和 OHOS 系统交互如处理触摸事件、系统消息平台通道通信阻塞可能间接卡 UI0.5 一帧是怎么画出来的渲染流水线每一帧画面都要经过四个阶段才能显示到屏幕上就像工厂的流水线Build → Layout → Paint → Composite光栅化 │ │ │ │ │ │ │ └─ Raster 线程把画面变成像素交给 GPU 上屏 │ │ └─ UI 线程生成绘制指令Layer 树 │ └─ UI 线程确定每个组件的大小和位置 └─ UI 线程执行你的 Dart 代码更新 Widget 树新手提示Build/Layout/Paint 在 UI 线程——如果你的 Dart 代码慢了这里会超时Composite 在 Raster 线程——如果画面太复杂大图、模糊、大量图层这里会超时排查卡顿时第一步就是搞清楚哪条线程超时了详细的分析方法见 Flutter OH 滑动卡顿丢帧与时延问题分析指南0.6 什么是帧预算屏幕每秒刷新 60 次或 90/120 次每次刷新叫一帧。每一帧必须在规定时间内画完这个时间就是帧预算屏幕刷新率帧预算通俗解释60Hz16.6ms每帧要在 16.6 毫秒内画完90Hz11.1ms每帧要在 11.1 毫秒内画完120Hz8.3ms每帧要在 8.3 毫秒内画完如果某一帧没在帧预算内画完这帧就丢了丢帧/Jank用户看到的就是卡了一下。打个比方就像翻页动画书每秒翻 60 页才能看起来流畅。如果某一页你翻了 50 毫秒才翻完动画就会卡一下。0.7 什么是响应时延和完成时延这是华为应用体验质量标准里的两个重要指标用户说卡很多时候是这两个时延出了问题指标通俗解释用户感受阈值举例响应时延从用户触摸到首个画面反馈的时间100ms 感觉迟钝点了按钮100ms 后界面才有反应完成时延从用户操作到整个操作彻底完成的时间视场景而定点开详情页白屏 2 秒才出内容新手区分响应时延是点了有没有立刻有反应——主线程被阻塞会导致响应慢完成时延是操作有没有彻底完成——数据加载慢、首屏构建太大会导致完成慢响应时延可能合格点了立刻有动画但完成时延崩了动画完了内容还没出来详细的量测方法见 Flutter OH 滑动卡顿丢帧与时延问题分析指南 §50.8 触摸事件是怎么变成画面的触摸到上屏的全链路当你手指滑动屏幕时事件要经过一条很长的传送链才能变成画面手指按下 │ ├─ mmi_service多模交互服务 │ └─ 立即转发给应用主线程DispatchTouchEvent │ ├─ 手指滑动move 事件 │ └─ 不立即转发由 vsync 信号门控随帧节奏派发 │ mmi_service → VSyncGennerator → DVSync-app → 应用主线程 │ ├─ TouchSlop 滑动阈值 │ └─ 系统判定开始滑动的最小位移默认 18vp │ └─ 渲染送显 └─ 1.ui → 1.raster → render_service → RSUniRenderThread → RSHardwareThread → 屏幕显示新手提示详细的 trace 链分析方法见 Flutter OH 滑动卡顿丢帧与时延问题分析指南 §2。0.9 什么是外接纹理外接纹理External Texture是一种让原生侧视频播放器、相机、动画等把画面喂给 Flutter 显示的机制。你可以把它理解为一个画面传送带生产者视频播放器 / 相机等原生组件持续产出画面帧消费者Flutter 引擎把画面帧绘制到屏幕上如果传送带出了问题生产太快消费不过来、生产者停了、消费者卡了就会导致画面黑屏、卡顿或冻结。0.10 什么是GPU 上下文丢失当应用退到后台或系统内存不足时OHOS 系统会回收 GPU 资源为了省电/省内存。这就好比你工作时电脑突然关了机——你的工作环境GPU 上下文丢了需要重新启动才能继续工作。Flutter 引擎会自动重建 GPU 上下文但重建期间画面会短暂黑屏。1. 故障速查1.1 我遇到的是什么问题根据你看到的现象找到对应的文档你看到的现象可能是什么问题去哪个文档应用闪退、崩溃Native 崩溃 / Dart 异常 / ETS 异常Flutter OH 崩溃问题定位指南应用卡死、无响应、点不动线程卡死UI/Raster/PlatformFlutter OH 卡死冻屏问题定位指南界面卡顿、滑动不流畅丢帧/JANK帧率不够Flutter OH 性能卡顿丢帧问题定位指南点了按钮反应慢、滑动跟手性差响应时延过长主线程被阻塞Flutter OH 滑动卡顿丢帧与时延问题分析指南页面打开白屏太久才出内容完成时延过长首屏构建/数据加载慢Flutter OH 滑动卡顿丢帧与时延问题分析指南手机发烫、耗电快、CPU 持续高占用负载异常 / 后台功耗持续重绘、轮询未停Flutter OH 负载异常与功耗问题定位指南内存占用过高、OOM 闪退Dart Heap 内存超限Flutter OH 内存与 GPU 问题定位指南黑屏、白屏、渲染异常GPU 上下文丢失退后台后恢复失败Flutter OH 内存与 GPU 问题定位指南视频/相机画面黑屏、不更新、卡顿外接纹理问题Flutter OH 外接纹理问题定位指南分栏不生效/避让失效/折叠屏异常多设备适配问题Flutter OH 多设备适配问题定位指南不确定是什么问题先抓全量日志再说Flutter OH 日志抓取与过滤指南1.2 故障定位决策树如果你不确定问题类型可以按以下步骤搜索日志关键词来判断应用出现异常 │ ├─ 应用闪退/崩溃 │ ├─ 日志中搜到 Caught signal SIG* │ │ → 引擎底层 C 崩溃Native 崩溃详见 dfx-crash.md §2 │ ├─ 日志中搜到 Unhandled Exception: │ │ → 你的 Dart 代码有未捕获的异常详见 dfx-crash.md §3 │ ├─ 日志中搜到 FLUTTER_ETS_EXCEPTION │ │ → ETSArkTS插件层异常详见 dfx-crash.md §4 │ └─ 以上都搜不到 │ → 先抓全量日志详见 dfx-logging.md │ ├─ 应用卡死/无响应 │ ├─ 日志中搜到 is not alive │ │ → 某个线程卡死了详见 dfx-appfreeze.md │ ├─ 日志中搜到 FLUTTER_THREAD_STUCK │ │ → 看门狗检测到线程卡死详见 dfx-appfreeze.md │ └─ 日志中搜到 APP_FREEZE │ → UI 线程卡死超过 6 秒系统要杀进程了详见 dfx-appfreeze.md │ ├─ 界面卡顿/丢帧 │ ├─ 日志中搜到 OTHER_JANK 或 OTHER_JANK_STAT │ │ → 非滑动场景丢帧详见 dfx-performance.md │ ├─ 日志中搜到 OTHER_JANK_SCROLL │ │ → 滑动场景丢帧详见 dfx-performance.md │ ├─ DevTools 中帧标红且只有 UI 线程超时 │ │ → Dart 代码慢build/layout/paint详见 dfx-jank-latency.md §4.1 │ ├─ DevTools 中帧标红且只有 Raster 线程超时 │ │ → 绘制太重大图/模糊/saveLayer详见 dfx-jank-latency.md §4.2 │ ├─ DevTools 标注 Shader Compilation Jank │ │ → 首次编译着色器导致详见 dfx-jank-latency.md §4.6 │ └─ 需要更详细分析 │ → 抓取 HiTrace详见 dfx-performance.md │ ├─ 响应时延 / 完成时延问题 │ ├─ 点击后反应慢响应时延长 │ │ → 主线程被重活阻塞详见 dfx-jank-latency.md §4.5 │ ├─ 页面打开白屏太久完成时延长 │ │ → 首屏全量构建 / 数据加载慢详见 dfx-jank-latency.md §4.5 │ └─ 需要量时延出数 │ → 用 FrameTiming 打点 系统 trace 链详见 dfx-jank-latency.md §5 │ ├─ 负载 / 功耗问题手机发烫、耗电快、CPU 持续高占用 │ ├─ top -H 发现某线程 CPU 持续高占用 │ │ → 用 hiperf 抓指令数采样 火焰图定位热点详见 dfx-power-load.md §2 │ ├─ 静止页面 CPU 仍不回落 │ │ → 无效重绘缺 const/RepaintBoundary详见 dfx-power-load.md §5.1 │ ├─ 退后台后仍在跑任务 / 定时器未停 │ │ → 后台功耗暂停动画/轮询/纹理详见 dfx-power-load.md §5.2 │ └─ 伴随 OTHER_JANK 事件 │ → 已影响流畅度交叉比对 HiTrace/HiLog详见 dfx-power-load.md §2.4 │ ├─ 内存问题 │ ├─ 日志中搜到 Dart heap memory usage exceeds threshold │ │ → Dart 内存超过 1.5GB详见 dfx-memory.md │ └─ 日志中搜到 FrameworkMemAnomaly │ → 系统记录了内存异常事件详见 dfx-memory.md │ ├─ GPU/渲染问题 │ ├─ 日志中搜到 GpuReclaim 且包含 kAggressive │ │ → GPU 资源被系统回收了详见 dfx-memory.md │ └─ 日志中搜到 FLUTTER_GPU_CONTEXT_LOSS │ → GPU 上下文丢失事件详见 dfx-memory.md │ ├─ 外接纹理问题视频/相机画面异常 │ ├─ 日志中搜到 No DlImage available 或 OH_NativeImage_Create() failed │ │ → 纹理创建失败或无画面详见 dfx-texture.md §5 │ ├─ 日志中搜到 frame gate enabled, drain-only │ │ → 应用在后台纹理帧被暂停正常行为详见 dfx-texture.md §6 │ ├─ 日志中搜到 skip one frame │ │ → 画面生产太快消费跟不上详见 dfx-texture.md §8 │ └─ 日志中搜到 PlatformViewVisibleAreaEventCallback │ → 可见区域变化触发了暂停/恢复详见 dfx-texture.md §7 │ ├─ 多设备适配异常 │ ├─ 日志中搜到 SplitView 或 SystemChannel config parse failed │ │ → 分栏配置问题详见 dfx-multi-device.md §2 │ ├─ 日志中搜到 avoidAreaChangeCallback │ │ → 安全区域避让问题详见 dfx-multi-device.md §3 │ ├─ 日志中搜到 Fold status change │ │ → 折叠屏状态变化详见 dfx-multi-device.md §4 │ ├─ 日志中搜到 Device pixel ratio │ │ → DPI 缩放问题详见 dfx-multi-device.md §5 │ ├─ 日志中搜到 LTPO │ │ → 自适应刷新率问题详见 dfx-multi-device.md §6 │ └─ 日志中搜到 windowSizeChangeCallback │ → 多窗口尺寸变化详见 dfx-multi-device.md §7 │ └─ 引擎生命周期异常 └─ 日志中搜到 FLUTTER_ENGINE_CREATE 或 FLUTTER_ENGINE_DESTROY → 引擎被创建或销毁详见 dfx-memory.md §4新手提示如果上面的关键词你不知道怎么搜别急先看 §2 学会抓日志。2. 第一步抓取日志无论遇到什么问题第一时间抓取日志是最关键的。就像破案要保护现场一样日志就是现场。2.1 快速抓取全量日志按这 4 步操作就行# 1. 清空历史日志清掉旧的只留复现后的新日志hdc shell hilog-r# 2. 复现问题操作你的应用触发 bug# 3. 抓取日志按 CtrlC 停止抓取hdc shell hilogflutter_log.txt# 4. 从日志中筛选 Flutter 相关的内容hdc shell hilog|grep-EFlutter|XComFlutter|flutterflutter_filtered.txt新手提示hilog就是 OHOS 的日志系统类似于 Android 的logcatgrep是文本搜索工具-E表示用正则表达式匹配表示把输出保存到文件2.2 按问题类型过滤日志只看相关内容过滤掉噪音不知道该用哪条回到 §1.1 对照你的现象选择# 崩溃相关应用闪退hdc shell hilog|grep-ECaught signal|Unhandled Exception|FLUTTER_DART_EXCEPTION|FLUTTER_ETS_EXCEPTION# 卡死相关应用无响应hdc shell hilog|grep-EFlutterWatchdog|not alive|HiCollie|THREAD_STUCK# 卡顿/丢帧相关界面不流畅hdc shell hilog|grep-EJANK|jank|missed|frame# 内存相关OOM、内存占用高hdc shell hilog|grep-Eheap memory|memory|OOM|threshold# GPU 相关黑屏、白屏hdc shell hilog|grep-EGpuReclaim|GPU|gpu# 外接纹理相关视频/相机画面异常hdc shell hilog|grep-Eexternal_texture|ExternalTexture|NativeImage|DlImage|frame gate|VisibleArea|texture_id# 多设备适配相关分栏、折叠屏等hdc shell hilog|grep-ESplitView|split_view|avoidArea|displayFeature|foldStatus|device pixel ratio|windowSizeChange|LTPO2.3 抓取性能 Trace分析卡顿专用如果界面卡顿但日志看不出问题需要抓取性能 Trace类似 Chrome DevTools 的 Performance 录制# 抓取 10 秒的性能 Trace在这 10 秒内复现卡顿hdc shell hitrace--trace_clockboottime-t10flutter-o/data/local/tmp/trace.ftrace# 把 Trace 文件拉取到电脑hdcfilerecv /data/local/tmp/trace.ftrace ./trace.ftrace# 用 Chrome 浏览器打开访问 chrome://tracing → 点击 Load → 选择 trace.ftrace详细的日志抓取与过滤方法请参考 Flutter OH 日志抓取与过滤指南。3. DFX 事件速查表Flutter 引擎在运行过程中会自动上报一些事件可以理解为结构化的崩溃报告每个事件都包含了问题类型、时间戳、进程 ID 等信息。事件名问题类型通俗解释去哪个文档FLUTTER_DART_EXCEPTIONDart 异常你的 Dart 代码有 bug 导致崩溃Flutter OH 崩溃问题定位指南FLUTTER_ETS_EXCEPTIONETS 异常ArkTS 插件代码有 bugFlutter OH 崩溃问题定位指南FLUTTER_STABILITY_EVENT稳定性事件引擎检测到不稳定卡死、GPU丢失等见下方子表OTHER_JANK丢帧某一帧渲染太慢导致卡顿Flutter OH 性能卡顿丢帧问题定位指南OTHER_JANK_STAT丢帧统计一段时间内的丢帧汇总Flutter OH 性能卡顿丢帧问题定位指南OTHER_JANK_SCROLL滑动丢帧滑动时某一帧超过 50msFlutter OH 性能卡顿丢帧问题定位指南FrameworkMemAnomaly内存超限Dart 内存超过 1.5GBFlutter OH 内存与 GPU 问题定位指南FLUTTER_STABILITY_EVENT 的子类型FLUTTER_STABILITY_EVENT是一个大类里面通过eventName字段区分具体是什么稳定性问题eventName通俗解释去哪个文档FLUTTER_THREAD_STUCK某个线程卡死了Flutter OH 卡死冻屏问题定位指南FLUTTER_GPU_CONTEXT_LOSSGPU 资源被系统回收Flutter OH 内存与 GPU 问题定位指南FLUTTER_ENGINE_CREATEFlutter 引擎创建了Flutter OH 内存与 GPU 问题定位指南FLUTTER_ENGINE_DESTROYFlutter 引擎销毁了Flutter OH 内存与 GPU 问题定位指南完整的事件参数说明请参考 Flutter OH DFX 事件目录参考。4. HiLog 关键字速查表在日志中搜索这些关键字可以快速判断问题类型搜索这个关键字问题类型含义通俗解释Caught signal SIGSEGV引擎崩溃引擎访问了非法内存比如空指针Caught signal SIGABRT引擎崩溃引擎内部断言失败或内存被破坏Unhandled Exception:Dart 异常你的 Dart 代码有未 try-catch 的异常is not alive卡死某个线程 3 秒没响应了OH_HiCollie_Report() success卡死卡死事件已上报到系统Dart heap memory usage exceeds threshold内存超限Dart 内存超过 1.5GBGpuReclaimkAggressiveGPU 回收系统正在回收 GPU 资源退后台时正常GpuReclaimkRestoreGPU 恢复GPU 资源正在恢复回前台时正常Poll error:消息循环异常系统消息循环出错可能导致卡死AwaitVSync...failedVsync 失败垂直同步信号请求失败可能导致不渲染No DlImage available外接纹理纹理没有可绘制的画面黑屏frame gate enabled外接纹理应用在后台纹理帧被暂停正常skip one frame外接纹理画面生产太快跳过了一些帧5. DFX 能力概览5.1 三套日志体系日志从哪里来Flutter OHOS 平台的日志来自三个不同的源头了解它们有助于精准过滤日志来源Tag谁产生的典型内容什么时候看引擎内部(FML_LOG)映射到 HiLogFlutter 引擎的 C 代码崩溃堆栈、卡死检测、GPU 回收排查崩溃、卡死、黑屏平台 C 层XComFlutterOHOS_NativeOHOS 平台的 C 代码引擎初始化、NAPI 调用排查引擎初始化问题ETS 嵌入层FlutterArkTS 代码MethodChannel、插件异常、生命周期排查插件/通道问题一条命令看全部 Flutter 日志hdc shell hilog|grep-EFlutter|XComFlutter|flutter5.2 DFX 上报通道问题信息记录在哪里通道通俗理解怎么查看HiLog实时文本日志hdc shell hilogHiAppEvent结构化事件带参数hdc shell hilog | grep OH_HiAppEvent_WriteHiCollie系统级卡死检测触发系统 APP_FREEZE 事件HiTrace性能追踪每帧耗时hdc shell hitrace ...5.3 API 版本要求有些功能需要高版本系统功能最低系统 API 版本低于此版本会怎样HiAppEvent 事件上报API 18不会生成任何 HiAppEvent 事件但 HiLog 仍可用HiTrace 扩展接口API 19丢帧详情 Trace 不可用内存异常上报 (FrameworkMemAnomaly)API 26不会上报内存异常事件但 HiLog 仍可用新手提示HiLog 日志不受 API 版本限制始终可用。如果发现某些事件搜不到先检查系统 API 版本。6. 文档索引文档讲什么什么时候看Flutter OH 日志抓取与过滤指南怎么抓日志、过滤日志所有问题排查的第一步Flutter OH 崩溃问题定位指南应用闪退/崩溃怎么查应用闪退、崩溃Flutter OH 卡死冻屏问题定位指南应用卡死/无响应怎么查应用点不动、卡死Flutter OH 性能卡顿丢帧问题定位指南界面卡顿/丢帧怎么查DFX 事件层面界面不流畅、滑动卡、查丢帧事件Flutter OH 滑动卡顿丢帧与时延问题分析指南滑动卡顿丢帧与时延问题深度分析卡顿优化、响应/完成时延量测、DevTools/SmartPerf 使用Flutter OH 负载异常与功耗问题定位指南负载异常与功耗问题怎么查手机发烫、耗电快、CPU 持续高占用、后台偷跑Flutter OH DFX 事件目录参考所有 DFX 事件的完整说明查事件参数含义Flutter OH 内存与 GPU 问题定位指南内存/OOM/GPU 问题怎么查内存高、OOM、黑屏Flutter OH 外接纹理问题定位指南外接纹理问题怎么查视频/相机画面异常Flutter OH 多设备适配问题定位指南多设备适配问题怎么查分栏、折叠屏、DPI 等