鸿蒙PC 崩溃译码工作台实战:用 ArkUI 把「报错排查—性能归因—方案治理」串成一条闭环

欢迎加入开源鸿蒙PC社区: https://harmonypc.csdn.net/
欢迎在PC社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper


前言:做桌面应用的团队都有一个共同痛点:崩溃上报里躺着一堆错误码,谁都看得见,但没人能在十分钟内说清「这条错误码在什么条件下会复发、改了哪行代码能让它不再出现」。手机端的排查经验搬到鸿蒙PC 上会立刻失效——2in1 桌面形态意味着窗口可以任意拉伸、鼠标 hover 每秒上百次、应用常驻数小时、后台任务与前台渲染同时在线,同一条 JSCrash 在手机上是一次偶发闪退,在鸿蒙PC 上可能是一整天的低频雪崩。本文拿一套真实的鸿蒙PC 工程当样本:应用「译崩 DECIPHR」是一个纯 ArkTS + ArkUI 的崩溃译码与故障排查工作台,deviceTypes 只保留 ['2in1'],SDK 26.0.0,零三方依赖。它把一次事故拆成五个工作面——事故看板、堆栈解剖、信号时间线、错误码词典、修复验证,最后沉淀成复盘档案。文章走三条线:报错排查(把错误码变成可复算的信号序列)、性能优化(Canvas 重绘时机、派生值缓存、key 稳定性、定时器回收)、方案选型治理(为什么用 Canvas 而不是几十个组件、为什么限定 2in1、以及 ArkUI 原生与跨平台框架在鸿蒙PC 上该怎么分工)。需要提前声明:本工程使用的是 ArkUI,不是 ArkUI-X,也没有引入任何跨平台框架运行时;文中数值分两类,一类是从源码静态数出来的(会给文件和行号),一类是界面上的演示数据(会明确标注它不代表任何实测性能),不混淆、不夸大。

关键词:鸿蒙PC、鸿蒙 PC、开源鸿蒙PC、崩溃排查、错误码词典、信号时间线、Canvas 重绘、无效重组、派生值缓存、ArkUI、跨平台框架、2in1 桌面、方案选型治理、AtomGit。


鸿蒙PC 真机桌面:崩溃译码工作台「事故看板」,右侧浮着一次构建与运行的原始报错输出

开篇图 鸿蒙PC 真机完整桌面:工作台停在「事故看板」页,窗口右侧还浮着一个报错输出浮层。顶栏是品牌区「译崩 · DECIPHR」、检索入口、「接入档案」按钮与六个页签(事故看板 / 堆栈解剖 / 信号时间线 / 错误码词典 / 修复验证 / 复盘档案);左侧「黑匣子档案流」是一列带严重级徽标、错误码、所属模块、发生次数与时间戳的卡片;中间是四张严重级统计卡(致命 2 / 错误 2 / 警告 2 / 提示 1)与逐行的档案列表(错误码、模块、标题、发生次数、影响用户数);右侧浮层是系统侧一次构建与运行的原始日志,末尾停在 …-default-signed.hap in 457 ms、m.triage.console in 245 ms、s in 725 ms 这几行耗时记录

这张图是全文的入口,也是本文写法的一次自我说明。中间那块界面是本工程画的,右侧那层浮层不是——它是系统侧一次构建与运行留下的原始报错输出,那几行 in 457 ms、in 245 ms、in 725 ms 是编译产物与任务的耗时,既不是界面上的演示数字,也不是我测出来的性能指标。把两者并排放着看,恰好能说明这个工作台要解决的矛盾:原始报错是散落的、带时序的、夹着堆栈和耗时的;而工程师真正需要的是可以归档、可以复算、可以验收的条目。 全文讨论的「报错排查—性能归因—方案治理」,就是在这两端之间搭桥,而不是再做一个日志查看器。

一、先把事实边界说清楚:截图、工程、待修代码各是什么

技术博客最容易失信的地方,是把「我看到的界面」当成「我测到的数据」。所以先分三层,后面所有论断都挂在这三层上。

第一层,问题样本:四张鸿蒙PC 真机完整截图。 四张图都是同一台鸿蒙PC 设备的完整桌面:底部是系统 Dock(文件、浏览器、邮件、应用市场、云空间、图库等一整套系统图标),右下角是系统托盘(网络、音量、电池)与「下午8:49 / 11月15日」时间,前台是一个满屏的深色工作台窗口,窗口标题栏里最小化、最大化、关闭三个系统按钮齐全,窗口标题写着「译崩 · DECIPHR」。其中开篇图与本节的图 1 同停「事故看板」页——开篇图右侧多挂了一层系统侧的报错输出浮层,图 1 是干净的工作台本体;图 2、图 3 分别停在「信号时间线」「修复验证」。它们是同一个应用的完整工作面,不是手机截图、不是应用内裁剪图,也不是设计稿。

第二层,配套工程:项目源码/Deciphr_ohos。 一个纯 ArkTS / ArkUI 声明式 UI、Stage 模型的 2in1 工程,应用名「译崩 · DECIPHR」,包名 com.deciphr.faultlab,deviceTypes 只有 ['2in1'],compatibleSdkVersion 与 targetSdkVersion 均为 26.0.0,工程级与模块级 dependencies 全为空。它没有接 FaultLogger、没有接 hiAppEvent、没有读任何系统崩溃日志——界面上的 7 条故障档案、26 个信号事件、5 条错误码释义、7 个修复项,全部来自 Models.ets 里的 FaultData 静态数据集。也就是说:截图回答「这个工作面长什么样」,工程回答「代码落在哪一行」,但界面上的 37 次、12 人、0/7 这些数字是演示数据,不是采集数据。

第三层,本文的补充实现。 第六至第九章给出的若干 .ets 片段,是对工程里静态可见缺陷的修复稿,全部用 ArkUI 原生能力写、可独立编译,文中会逐条标明改哪个文件、改哪几行、改完之后能看到什么变化。它们不冒充实测性能报告,只承诺一件事:改前改后的行为差异可以用眼睛复现。

三层互不冒充,是本文结论可信的前提。后面凡是写「静态可见」,都会给出文件与行号,读者可以自己数一遍;凡是写「估算」,都会说明估算依据。

二、三张鸿蒙PC 真机截图:先看工作面,再谈代码

鸿蒙PC 真机完整桌面:事故看板页

图 1 鸿蒙PC 真机完整桌面:「事故看板」页。左侧是黑匣子档案流(7 条档案,每张卡带严重级徽标、错误码、标题、所属模块、发生次数与时间戳),中间是四张严重级统计卡(致命 2 / 错误 2 / 警告 2 / 提示 1)与档案列表(错误码、模块、标题、次数、影响用户数),顶栏是品牌区、检索入口、「接入档案」按钮与六个页签

图 1 是主战场。请注意三件事:第一,左侧档案流与中间档案列表展示的是同一批数据,只是投影不同——左边是带时间戳的卡片,右边是按严重级归档的行;第二,每一行右侧有两个数字列(发生次数、影响用户数),这两个数字在代码里是 FaultRecord 的普通字段,不是聚合查询结果;第三,顶部六个页签是 if / else 互斥分支,不是路由栈。这三点决定了「点一次页签」在鸿蒙PC 上要付多少代价:它不只是换一块内容,而是让整个状态中心重新执行一次视图描述。

鸿蒙PC 真机完整桌面:信号时间线页

图 2 鸿蒙PC 真机完整桌面:「信号时间线」页。页签带橙色下划线表示当前激活,标题区下方是「崩溃前各信号通道的强度序列,高度代表对崩溃的贡献权重」的说明,主体是一整块深色 Canvas 画布,当前显示居中占位文案「选择档案后绘制信号时间线」

图 2 是全文最值得看的一页,因为它把「空态」摊在了 1080×720 的完整桌面里。这块占整页面积的画布是一个 Canvas 组件,占位文案由 draw() 在 fault === null 分支里用 fillText 画出来——也就是说,这块「什么都没画」的区域,其实已经执行过一次完整的绘制流程。当用户从左侧选中一份档案时,本该在这块画布上出现 2 到 6 根不等高的信号柱、一条时间轴和五条刻度。而这份代码里这条路是断的,第六章会把断点和修复一起摊开。

鸿蒙PC 真机完整桌面:修复验证页

图 3 鸿蒙PC 真机完整桌面:「修复验证」页。顶部三张统计卡(已采纳 0/7、验证通过 0、待验证 7),下方 7 条修复项,每条带勾选圆点、修复标题、目标模块、工作量评级、「验收口径」与右侧橙色「沙盒验证」按钮

图 3 信息密度最高,也最能说明「治理」在工程里的含义:每一个修复项都被强制绑定一条可量化的验收口径——「主线程占用 < 45%」「SIGSEGV 不再复现」「Freeze 事件归零」「48h 堆增长 < 10MB」「-109 频次降 90%」「丢帧率 < 5%」「EIO 转静默清理」。这条验收口径不是装饰文案,它决定了这个修复项能不能被判定为「通过」。统计卡里 0/7、0、7 的对比正是这条规则的直接后果:没有勾选采纳,就没有资格进入验证。

三、为什么「崩溃排查台」在鸿蒙PC 上也要谈性能

把性能问题归到一套排查工具上,需要一条讲得通的因果链,而不是一句「优化总是好的」。在鸿蒙PC 的 2in1 桌面形态上,这条链至少有四站。

第一站是视图描述重建。 ArkUI 是声明式 UI 框架:状态变化后框架重新执行 build() 生成新的视图描述,再与旧树做差分,只把差异提交给渲染管线。差分的成本取决于「树的规模」与「差异的粒度」。本工程把所有状态都压在 pages/Index.ets 一个 struct 里,@State 一共 10 个(faults、fixes、selectedId、view、keyword、showSearch、showAttach、toastMsg、toastOn、verifyTick),其中任何一个变化都会让 Index.build() 完整执行一次;六个页签又是 if / else if 的互斥分支,所以「当前页签有多大」直接等于「一次状态更新的描述成本」。事故看板一屏有 7 条档案行加 4 张统计卡,修复验证一屏有 7 条修复行加 3 张统计卡,都不是小树。

第二站是测量与布局。 桌面窗口宽度可变。InkMetrics.railWidth = 264 是固定值,右侧工作区用 layoutWeight(1) 吃掉剩余宽度,InkMetrics.pagePad = 22 决定四边留白。用户在鸿蒙PC 上拖动窗口边缘时,每一次宽度变化都会引发级联测量;Scroll 里的内容一旦高度变化(例如切换页签后列表长度不同),滚动容器的内容尺寸也要重算。手机上一屏基本固定,鸿蒙PC 上用户会主动、连续、高频地改变它。

第三站是绘制节点的数量。 这套界面没有位图图标,全部是 Text 字形符号(◉、⌕、§、✎)加 Circle、Column、边框绘制的几何装饰。按图 1 静态展开数一遍:一条档案行由 8 个 Text 叶子加 3 个容器组成(严重级徽标、错误码、模块、标题、次数、状态词、影响数、列标签),一屏 7 行就是 56 个 Text;顶栏另有 6 个页签节点、3 个装饰圆点和 2 个操作入口。桌面 DPI 高、窗口大、绘制面积大,节点数与描边宽度的组合直接决定 GPU 侧栅格化压力。

第四站是事件与常驻。 鸿蒙PC 上有两件手机没有的事:一是鼠标 hover,指针以每秒上百次频率扫过按钮;二是窗口常驻,一套排查工作台会被工程师开一整天,同一块画布、同一批列表被反复刷新。两者都是「高频、小信息量」的输入,天然容易触发过量重绘。再加上工程师的使用习惯是「左手点档案、右手切页签」,状态写入频率远高于普通阅读类应用。

这条链条给出一个实用的优化顺序:先把「一次重建的粒度」做小(派生值缓存、key 稳定、状态下沉),再把「重建与重绘的次数」做少(重绘时机、事件收敛),最后才是「节点本身更轻」(图标资源化)。 反过来先抠图标,收益会被重建掩盖掉。

四、工程基线盘点:把目标态钉死在文件里

动手之前先把真实配置核一遍。下表的每一项都能在源码里查到,不是估计值。

项实际值证据
应用 / 包名「译崩 · DECIPHR」/ com.deciphr.faultlabAppScope/app.json5
版本versionCode 1000000、versionName 1.0.0AppScope/app.json5
设备形态仅 ['2in1'],无 phone / tabletentry/src/main/module.json5
SDKcompatibleSdkVersion / targetSdkVersion 均 26.0.0,runtimeOS: HarmonyOSbuild-profile.json5
构建模型hvigor + ohpm,Stage 模型,strictMode.useNormalizedOHMUrl: truebuild-profile.json5
三方依赖工程级、模块级 dependencies 全为空oh-package.json5
页面入口windowStage.loadContent('pages/Index'),单页应用entryability/EntryAbility.ets:12
源码规模14 个手写 .ets,合计约 1839 行entry/src/main/ets/
状态中心Index.ets 221 行、10 个 @State、六个页签互斥分支pages/Index.ets:16-28
数据层Models.ets 309 行,7 档案 / 26 信号事件 / 19 栈帧 / 5 错误码 / 7 修复项common/Models.ets
画布单个 Canvas,draw() 仅在 onReady 与 onTouch(Up) 调用components/SignalTrace.ets:12,142,143
主题硬编码色板 17 色 + 字号 5 级 + 尺寸 6 项common/Theme.ets

这张表说明两件事。其一,这是一个零三方依赖的鸿蒙PC 原生 2in1 工程,进程启动后直接加载单页,没有框架运行时抢主线程,所以任何卡顿都更容易归因到业务代码本身;代价是所有采样、统计、导出都得自己写。其二,桌面形态适配只做了一半:宽度用固定值,没有跟随窗口做断点收敛;hover 只做了按钮级着色,没有做事件合并。

再把数据层的规模数干净,后面算成本才有分母:FaultData.faults() 构造 7 个 FaultRecord、19 个 StackFrame、26 个 SignalEvent;7 条档案累计发生 163 次、影响 59 人;严重级分布是致命 2、错误 2、警告 2、提示 1。FaultData.codes() 构造 5 个 CodeEntry,FaultData.fixes() 构造 7 个 FixItem。这个量级小到不会成为瓶颈,正因如此,任何写法的浪费都能被单独看见——这是拿它当性能样本的最大优势。

也必须坦白它的另一面:这个工程目前是方法论原型,不是可用的排查工具。三处证据:Models.ets:145-264 的 7 条档案是写死常量,device/system 字段是「MateBook 16s / HarmonyOS 6.0」这类演示字符串;Index.ets:91-104 的沙盒验证不是真的回放,而是 setTimeout 1600 ms 后把 passed 置真;Index.ets:182-184 的「导出报告」只弹一个 toast。换句话说,它验证的是流程形状,不是数据管道。想把它变成真工具,第一件事是接 FaultLogger 与 hiAppEvent,把 FaultData 换成异步加载的档案仓库。

五、报错排查:把错误码拆成可复算的信号序列

排查工具的第一性原理不是「列出错误码」,而是「把错误码还原成一条带时间戳的证据链」。本工程用三个结构承担这件事:FaultRecord 承载档案身份与统计,StackFrame 承载调用栈与疑点帧,SignalEvent 承载崩溃前的信号序列(offsetMs、kind、detail、weight)。

// common/Models.ets:58-71
export class SignalEvent {
  offsetMs: number;
  kind: string;
  detail: string;
  weight: number;

  constructor(offsetMs: number, kind: string, detail: string, weight: number) {
    this.offsetMs = offsetMs;
    this.kind = kind;
    this.detail = detail;
    this.weight = weight;
  }
}

四个字段各有分工:offsetMs 是相对崩溃时刻的毫秒偏移(负数表示崩溃前),kind 是信号通道(LOAD/CPU/MEM/JANK/WATCHDOG/CRASH/IO/THREAD/IPC/NET/RETRY/RATE/DECODE/ANIM/DISK/LEAK/ERROR/FREEZE/USER),detail 是人类可读的证据描述,weight 是「这条信号对本次崩溃的贡献权重」,取值 0 到 1。把 weight 映射成柱高、把 offsetMs 映射成横坐标,就得到图 2 那块画布上本该出现的可视化。

以工程里最有代表性的那条档案为例,BX-0417 / JSCrash 401「图库网格批量解码时主线程阻塞崩溃」的信号序列是这样的:

偏移通道证据权重
T-3.2sLOAD进入图库页,批量任务入列 86 张0.35
T-2.1sCPU主线程占用升至 97%,连续 1.8s0.80
T-1.6sMEM解码缓存瞬时增长 214MB0.55
T-0.8sJANK掉帧计数 47,最长帧 1.2s0.70
T-0.12sWATCHDOG主线程超时告警 8s 触发1.00
T+0CRASHJSCrash 401 进程终止1.00

这张表就是一条归因链的骨架,也是排查方法论的落点:

  1. 先看末端。CRASH 权重恒为 1,它是结论不是原因,永远从它往前一列找。
  2. 再看谁先到 1.0。WATCHDOG 权重 1.0 意味着系统已经判定超时,此时主线程已经死了 8 秒,比它更早的 CPU 97%、JANK 最长帧 1.2s 只是前兆,真正的因果在 LOAD 那一格——86 张缩略图在同一帧内集中提交。
  3. 最后回到栈。BX-0417 的 5 个栈帧里,isRootCause 打在第 0 帧 DeciphrDemo::decodeBatch(buf: ArrayBuffer[]) 上,文件 ImageBatcher.ets:188,帧类型 arkts;往下依次是 flushPending()、GridPage.aboutToAppear()、框架层的 ViewPU.updateStateVars()、系统层的 watchdog_kill(main_thread, 8000ms)。疑点帧在业务层,而不在框架层和系统层——这是判断「该改谁的代码」的关键一步,很多排查工作就死在这一步:把框架帧当成根因,然后去写 workaround。

同一套方法在另外几条档案上得到复用,也覆盖了鸿蒙PC 上最常见的几类失败模式:CPPCrash SIGSEGV 是取消路径的竞态(ExportTask::onCancel() 先 close() 句柄,写线程仍在派发残余分片,exporter_write_chunk(handle*, uint8_t*) 命中 addr=0x0);AppFreeze 0NOA 是渲染路径内做同步 IPC(ToggleRow.build() 每帧触发 12 次 SettingsStore.getItemSync,句柄服务队列深度 64 满载,主线程连续 3.1 s 无响应);Leak 48h +186MB 是监听器注册无幂等(每次重连成功都 registerNetListener(),48 小时堆增长 186MB);NET -109 是退避计时器被新任务重置导致重试风暴。这四类问题在鸿蒙PC 上的共性只有一个:它们都不是「某一行写错了」,而是「某条路径缺少一个约束」——缺切片、缺两阶段取消、缺快照缓存、缺幂等标记、缺全局退避。这也是为什么工程要单独做一份「错误码词典」,把成因和处置步骤固定下来。

// common/Models.ets:266-286(节选)
const c1 = new CodeEntry('JSCrash 401', 'JS 运行时',
  '主线程超时看门狗终止进程,多由单帧内重计算引发。');
c1.causes = ['单帧集中提交重任务', '同步 IO 阻塞主线程', '超大集合一次性布局'];
c1.steps = ['按信号时间线定位超时前最后稳定点', '把批量任务切片放入 TaskPool',
  '给看门狗阈值内的关键路径加分段日志'];

注意 steps 的写法:三条步骤严格按「定位 → 改造 → 观测」排列,第一步是取证,第二步是改代码,第三步是加可验证的观测点。这个顺序不能颠倒——先改造后定位,等于在没有基线的情况下改代码,改完既不知道有没有效果,也不知道有没有引入新问题。

六、性能优化一:让 Canvas 只在「数据真的变了」时重绘

回到图 2 那块画布。SignalTrace 是这个工程里唯一一个「命令式绘制」的组件:draw() 用 CanvasRenderingContext2D 一笔一笔画时间轴、刻度、圆角信号柱和通道标签,全程不走声明式 UI。先看它的完整绘制入口:

// components/SignalTrace.ets:12-96(节选)
draw() {
  const c = this.ctx;
  const w = c.width;
  const h = c.height;
  c.clearRect(0, 0, w, h);
  const f = this.fault;
  if (f === null || f.signals.length === 0) {
    c.fillStyle = InkColors.boneFaint;
    c.font = '16px sans-serif';
    c.textAlign = 'center';
    c.fillText('选择档案后绘制信号时间线', w / 2, h / 2);
    return;
  }
  const padL = 24;
  const padR = 24;
  const axisY = h - 56;
  const span = Math.max(1, -f.signals[0].offsetMs);
  const usableW = w - padL - padR;
  // …… 画轴线、五条刻度、按 weight 计算柱高的信号柱 ……
}

坐标映射只有两行是关键:横坐标 x = padL + usableW * (1 + s.offsetMs / span),柱高 hgt = 30 + s.weight * (axisY - 110)。span 取「第一条信号的偏移绝对值」,所以时间轴左端永远对齐最早那条信号,右端固定是 T+0 崩溃时刻——这是一个很好的取舍:不追求跨档案的时间轴可比性,只追求单档案内部的相对关系清晰。如果要做跨档案对比,就得把 span 提到组件外面做全局归一化,代价是所有档案的柱子都会变细,可读性下降。演示工具优先可读性,这个选择是对的。

但绘制入口的调用点是坏的。全文只有两处调用 draw():

// components/SignalTrace.ets:139-142
Canvas(this.ctx)
  .width('100%')
  .height('100%')
  .onReady(() => this.draw())

另一处在 onTouch 的 TouchType.Up 分支里(SignalTrace.ets:143-161),用户在画布上点一下,命中最近的柱子就重绘并高亮。问题是:fault 变化时没有任何东西调用 draw()。 组件里声明了 @Prop redrawTick: number = 0(SignalTrace.ets:7),但从头到尾没被读过一次,Index.ets 也从来没给它传过值——这是一个典型的「预留了刷新钩子却忘了接线」。后果非常直观:用户在左侧档案流里从「事故看板」横跳到「信号时间线」,fault 从 null 变成一条真档案,build() 会重新执行(标题、错误码、通道圆点这些声明式内容都会更新),但画布内容停在上一帧,仍然显示「选择档案后绘制信号时间线」。只有当用户用鼠标在画布上点一下,onTouch 触发 draw(),柱子才会突然出现。这就是图 2 那张空态截图背后真实存在的缺陷:声明式部分和命令式部分走了两套更新机制,而命令式那一套少了一根线。

修复只需要三行,不需要重构:

// components/SignalTrace.ets:改用 @Watch 接管重绘时机
@Prop @Watch('onFaultChanged') fault: FaultRecord | null = null;

private onFaultChanged(): void {
  // onReady 之前画布尺寸为 0,此时绘制会画出空白,交给 onReady 兜底
  if (this.ctx.width > 0 && this.ctx.height > 0) {
    this.draw();
  }
}

再把窗口尺寸变化也接上,因为鸿蒙PC 上画布宽度跟着窗口走,拖动窗口后必须按新宽度重算 usableW,否则柱子会被拉伸或截断:

// components/SignalTrace.ets:139-142
Canvas(this.ctx)
  .width('100%')
  .height('100%')
  .onReady(() => this.draw())
  .onAreaChange(() => this.draw())

这两处改动合起来,回答了一个被很多人忽略的问题:Canvas 的重绘时机应该由「数据变化」和「尺寸变化」两个事件驱动,而不是由组件生命周期驱动。 onReady 只保证画布拿到了上下文,它不保证数据是最新的;build() 重跑也不保证画布会重画。把 @Watch 挂在 @Prop 上,正好是把「数据变化」这件事显式地接到命令式绘制上;onAreaChange 则覆盖「尺寸变化」。两者都到位之后,那个从未被使用的 redrawTick 就可以删掉了——死代码比 bug 更贵,因为它会让后来的人以为刷新链路是通的。

顺带说一个成本上的细节:draw() 每次执行都会 clearRect 整块画布再重画所有元素,代价与画布面积成正比。在鸿蒙PC 上画布面积随窗口变化,从 1400×600 拉到 2400×1000,像素量涨近 3 倍。所以「只在需要时重绘」在桌面上比在手机上更重要:手机上画布尺寸基本不变,桌面上用户每一次拖拽窗口边缘都可能触发 onAreaChange。如果后续要做拖拽时的实时重绘,正确做法是节流——用一个 setTimeout 合并 16 ms 内的连续回调,而不是每来一次事件就画一遍。

七、性能优化二:派生值别在 build() 里现算

第二个问题比第一个隐蔽,因为它在 7 条数据的规模下完全看不出症状。CrashBoard 的四张统计卡要显示致命、错误、警告、提示各几条,实现是这样的:

// components/CrashBoard.ets:10-18
private countOf(s: Severity): number {
  let n = 0;
  for (const f of this.faults) {
    if (f.severity === s) {
      n += 1;
    }
  }
  return n;
}

然后在 build() 里被调用四次(CrashBoard.ets:117-122)。这意味着每一次重建都要把 7 条档案遍历四遍,得到四个数字。7 条时是 28 次比较,肉眼不可见;如果这个看板接上真实数据、档案涨到 500 条,就是每帧 2000 次比较,而结果在一个刷新周期内根本不会变。

同类问题在工程里还有三处,都可以用同一把尺子量出来:

  1. CodeBook.filtered()(CodeBook.ets:11-20)在 build() 里调用 FaultData.codes(),每次重建都重新构造 5 个 CodeEntry 对象再全表扫描一遍做过滤。对象是新的,ForEach 的 key 用的是 c.code 字符串,所以节点不会重建(key 稳定救了它),但过滤本身是纯浪费。
  2. StackLab 在 build() 里直接调 FaultData.causesFor(this.fault)(StackLab.ets:144),每次重建新建 4 个 CauseNode,ForEach 的 key 用的是 n.label——用文案做 key,一旦某条归因链的措辞改动,整列节点会被销毁重建。
  3. FixVerify 的 appliedCount() 与 passedCount()(FixVerify.ets:12-30)都在 build() 里被调用,而 build() 里 this.fixes.length - this.passedCount()(FixVerify.ets:136)又调了一次,于是「已通过数」在一次重建里算了两遍。

治理办法不是「到处加缓存」,而是把派生值从视图层搬到数据变更点。改法可以很小:统计在档案列表变化的那个时刻算好,视图层只读结果。

// pages/Index.ets:新增一个纯数据类,把三档统计提前算好
class BoardStat {
  fatal: number = 0;
  error: number = 0;
  warn: number = 0;
  info: number = 0;
}

// Index 内
@State boardStat: BoardStat = new BoardStat();

private recount(): void {
  const s = new BoardStat();
  for (const f of this.faults) {
    if (f.severity === 'fatal') {
      s.fatal += 1;
    } else if (f.severity === 'error') {
      s.error += 1;
    } else if (f.severity === 'warn') {
      s.warn += 1;
    } else {
      s.info += 1;
    }
  }
  this.boardStat = s;   // 整体替换引用,显式触发一次刷新
}

CrashBoard 改成接收一个 boardStat: BoardStat 的入参,build() 里只写 Text(${this.boardStat.fatal})。这样一次刷新周期里,遍历从 4 次降到 0 次,代价是档案数据变更时要记得调一次 recount()。这就是「治理」这个词的实际含义:不是消灭计算,而是给计算安排一个确定的时机和唯一的归属。

顺带说一个 ArkTS 的硬约束,很多从 Web 转过来的同学会踩:build() 里不能声明局部变量(不能 let / const),也不能写任意语句,它只允许 UI 描述语法。所以「在 build() 开头算一次,后面用四次」这条路是走不通的——这恰恰是把派生值赶回数据层的语言级理由。

八、性能优化三:状态写在「对的那一层」,定时器收在「走的那一扇门」

第三个问题跟性能无关,跟正确性有关,但它同样只在鸿蒙PC 的长驻场景下才会暴露。先看 Index.onDecode():

// pages/Index.ets:146-156(节选)
StackLab({
  fault: this.selected,
  onDecode: () => {
    const s = this.selected;
    if (s !== null) {
      s.decoded = true;
      this.toast('译码完成:' + s.code + ' 已解析出归因链');
    }
  }
})

这里改的是数组元素内部的一个字段(s.decoded = true),this.faults 这个数组引用本身没有变。ArkUI 的状态观察建立在「引用替换」上:@State 装饰的数组,只有整体赋值新数组时才会被标记为脏。所以严格来说,这一行不会触发任何刷新。它之所以在演示里「看起来生效了」,是因为紧接着的 this.toast() 改了 toastMsg 和 toastOn 两个 @State,把整个 Index 重建了一遍,顺带把新状态带了出去。这是侥幸,不是设计。 只要哪天有人把 toast 换成原生 promptAction(不进状态树),译码状态就会静默失效,而且极难排查——因为「点了有反应(toast 弹了),但列表状态没变」。

正确的写法是把「对象字段变更」显式翻译成「引用替换」:

// pages/Index.ets:把嵌套对象变更收敛成一次显式刷新
private markDecoded(id: string): void {
  for (const f of this.faults) {
    if (f.id === id) {
      f.decoded = true;
    }
  }
  this.faults = this.faults.slice();   // 关键:替换引用
}

this.fixes 的处理是全工程唯一做对的地方(Index.ets:69、87、100 三处都有 this.fixes = this.fixes.slice()),可以直接照抄。这类「同一个工程里两种写法并存」的现象在真实项目里极其常见,它说明规范不能靠自觉,得靠机制:要么统一走不可变更新工具函数,要么在 code review 清单里加一条「改了数组元素的字段吗?替换引用了没?」

第二件事是定时器。Index 持有两个定时器句柄:toastTimer 和 runTimer。toastTimer 在下次 toast 时会被 clearTimeout(Index.ets:52-54),处理得没问题;但整个 struct 没有 aboutToDisappear(),页面销毁时两个句柄都不会被清理。在手机上这条路径很少走到(应用一退后台就冻结),在鸿蒙PC 上情况不同:用户关掉窗口、切换账号、重进应用都是常规操作,残留的 setTimeout 回调会在组件销毁后继续跑,回调里改的 @State 落在已卸载的节点上。轻则日志里出现「找不到组件」的告警,重则把新页面的状态写脏。

// pages/Index.ets:补上销毁时机
aboutToDisappear(): void {
  if (this.toastTimer >= 0) {
    clearTimeout(this.toastTimer);
    this.toastTimer = -1;
  }
  if (this.runTimer >= 0) {
    clearTimeout(this.runTimer);
    this.runTimer = -1;
  }
}

第三件事更微妙,是一个一旦触发就会永久锁死按钮的分支。runVerify() 用一个自增的 verifyTick 做「防止旧回调覆盖新结果」的守卫:

// pages/Index.ets:88-104(节选)
this.verifyTick += 1;
const tick = this.verifyTick;
this.runTimer = setTimeout(() => {
  if (tick !== this.verifyTick) {
    return;                       // 注意这里:直接返回,没有把 runTimer 复位
  }
  // ……置 passed = true、复位 runTimer……
}, 1600);

而 runVerify() 的入口守卫是 if (target === null || this.runTimer >= 0) { return; }。也就是说:只要 tick !== this.verifyTick 这条早退分支被执行过一次,runTimer 就永远停在非负值,之后所有「沙盒验证」按钮点击都会被静默吞掉,界面从此不再响应。 目前这条分支因为 verifyTick 只在 runVerify 内部自增、而 runVerify 又被 runTimer 挡在门外,所以事实上不可达——但这是一颗定时炸弹:哪天有人为了「重跑验证」把 verifyTick += 1 挪到守卫外面,或者加个 @State 让它被外部重置,炸弹立刻引爆,且症状是「按钮点了没反应」,排查方向会被完全带偏。

修法只有一行,把复位提前到早退之前:

this.runTimer = setTimeout(() => {
  this.runTimer = -1;             // 先释放闸门,再判断是否需要丢弃结果
  if (tick !== this.verifyTick) {
    return;
  }
  // ……后续逻辑不变……
}, 1600);

这三件事放在一起,构成了本节的主张:性能治理和缺陷治理是同一件事的两个侧面,它们的共同敌人都是「隐式」——隐式的刷新时机、隐式的生命周期、隐式的状态归属。 把这三样都写成显式的,代码可能多出十行,但从此每一次「点了没反应」都能顺着一条窄路查到根因。

九、方案选型治理一:为什么这块画布必须是 Canvas,而不该是三十个组件

SignalTrace 用命令式绘制,这件事值得专门论证一次,因为它是全工程争议最大的一个技术选择。先算一笔账:一条档案最多 6 个信号事件,如果改用声明式组件画,每个柱子至少需要「圆角矩形 + 通道标签」两个节点,还要为 hoverIdx 高亮准备一个条件分支;再加深色底、时间轴、五条网格刻度、五个刻度标签,一屏大约需要 30 个节点,而且每个柱子的高度是 weight 算出来的百分比,横向位置是 offsetMs 算出来的偏移——这意味着每个节点都得挂 position 或 margin 做绝对定位。

用 Canvas 画,这些全部塌缩成 1 个节点,内部是若干次 beginPath / fill 调用。对比一下两种方案的代价结构:

维度声明式组件(约 30 节点)Canvas(1 节点 + N 次绘制调用)
首帧布局30 个节点参与测量与布局1 个节点参与布局,内部位置由绘制决定
数据更新30 个节点参与差分0 个节点差分 + 1 次整块重绘
尺寸自适应每个节点按百分比重排draw() 里用 c.width 重算一次
命中检测天然支持,事件冒泡到每个节点自己写坐标比较(本工程 30 vp 阈值)
可访问性每个节点可独立配置无障碍属性整块画布一个语义
调试成本可用 ArkUI Inspector 逐节点看只能靠 draw() 里的日志
代码量约 110 行声明式描述约 85 行绘制指令

结论很清楚:当图表元素数量大、位置由数据算出、且不需要逐元素交互时,Canvas 的优势是压倒性的。 反过来,一旦需求变成「每根柱子可点击、可弹浮层、可单独做无障碍朗读」,Canvas 立刻变成负担——你得手写命中检测、手写浮层定位、手写语义。本工程选了 Canvas,是因为它的交互需求只有一个:点一下高亮最近的一根柱子(SignalTrace.ets:143-161 只用了 30 vp 的横坐标阈值比较,连纵坐标都不比),其余全部只读。

这个判断标准可以固化成一句话,用来治理后续所有类似争论:「是否需要逐元素交互」是选型的第一分水岭,「元素数量是否随数据增长」是第二分水岭。 两者都否,用 Canvas;前者是后者否,用组件加懒加载;前者否后者是,用 Canvas 加命中检测表;两者都是,才考虑引入图表库——而引入图表库这件事,在本工程这种零依赖基线里,代价远大于收益:一个第三方图表库通常要带进几百 KB 的运行时和一套自己的布局系统,为了画 6 根柱子,不值得。

第二个选型点是单页 + 状态机,还是多页 + 路由。六个页签被写成了 if / else if 的互斥分支(Index.ets:137-186),没有用 Navigation,也没有 router 跳转。这么做的理由有三条:其一,六个工作面共享同一份「当前选中档案」,用状态机传递比用路由参数传递更直接,也避免了跨页状态同步;其二,切换页签时左侧档案流不重建,用户的位置感不丢——这在桌面多任务场景里很重要,工程师会一边看堆栈一边切到词典查码;其三,单页没有路由栈,返回键行为简单。代价也很实在:六个页面的代码全部堆在 Index.build() 里,一旦页签涨到十个,这个方法会变成灾难。治理线应该画在「六个」这个位置上:超过六个,就该把每个分支抽成独立组件并用 Navigation 的 NavDestination 管理,而不是继续往 build() 里塞 else if。

第三个选型点是为什么 deviceTypes 只留 2in1。这套界面的布局前提是「左侧 264 vp 固定栏 + 右侧自适应工作区 + 顶栏 108 vp 双层导航 + 22 vp 四边留白」,这个前提在手机竖屏上直接不成立:264 vp 的固定栏在 360 vp 宽的屏幕上会吃掉 73% 的宽度。与其写三套断点然后每一套都半残,不如老实声明「这是一个桌面工具」。module.json5 里 deviceTypes: ['2in1'] 不是偷懒,是用元数据把不可用的形态提前拦在安装环节,让用户根本装不上,而不是装上之后看到一个挤成一团的界面。这是治理里最省钱的一种手段:把问题前移到配置。

十、方案选型治理二:ArkUI 原生与跨平台框架在鸿蒙PC 上的分工

写到这里必须回答一个很多人会问的问题:这套东西为什么不用跨平台框架做?毕竟「一套代码多端跑」听起来很美。

先把词用准。本工程用的是 ArkUI——鸿蒙的声明式 UI 开发框架,@Entry / @Component / @State / @Prop / @Builder / Canvas / layoutWeight 这一整套都是它的原生能力,编译目标是 ArkTS 字节码,运行在系统的 ArkUI 渲染管线里。它不是 ArkUI-X(那是把 ArkUI 的声明式范式投射到 Android / iOS 的跨平台框架),本工程也没有引入 Flutter、Compose Multiplatform 或任何跨平台框架运行时。这一点必须在文章里说清楚,因为「ArkUI」和「跨平台框架」经常被混着用,一旦混用,后面所有关于「性能归因到哪一层」的结论都会失真。

那跨平台框架在鸿蒙PC 上到底该放在什么位置?我的判断是按「形态耦合度」切三刀:

第一刀,强耦合桌面的工具类应用(本项目)——用 ArkUI 原生。 判据是「这个东西离开 2in1 桌面就不成立」。崩溃排查台需要左侧档案流常驻、需要一块大面积画布随窗口拉伸、需要 22 vp 的桌面留白、需要鼠标 hover 的精细反馈。这些恰好是跨平台框架最薄的一层:窗口尺寸变化的事件语义、指针类型(鼠标 / 触控 / 手写笔)的区分、系统 Dock 与托盘的存在感,各家实现差异最大,抽象层的泄漏也最多。这种情况下,跨平台框架省下的那点开发量,会被「适配 2in1 形态」的补丁全部吃掉。

第二刀,弱耦合的业务应用——可以考虑跨平台框架。 表单、列表、详情、设置这类界面在鸿蒙PC 上和在其他端上长得几乎一样,抽象层的泄漏很小,一套代码多端跑是真的能省人力。此时要付出的代价是启动时的框架初始化、包体增量和一层额外的视图中间层——在鸿蒙PC 上这些代价是可以接受的,因为用户对桌面应用的首屏期望本来就没有手机那么苛刻。

第三刀,纯展示型内容——静态页面或 Web 容器就够,不必上框架。 这一刀最容易被忽略,但省下来的成本最多。

对本项目来说,选 ArkUI 原生还有一个具体收益:性能归因的链条是完整的。第七章里「build() 里算四次统计」这条结论之所以能直接落到行号上,是因为从 ArkTS 源码到渲染管线之间没有第三方运行时插在中间。如果换成跨平台框架,同样一次卡顿要先排除框架自己的调度开销,再排除桥接层的序列化开销,最后才轮到业务代码——归因成本会翻好几倍。对一套「排查工具」来说,这恰恰是最不能接受的:你自己都归因不清,凭什么帮别人归因。

十一、复现清单与踩坑记录

想把这套工程跑起来、把本文的修复验证一遍,按下面走。所有命令都在 DevEco Studio 的 Terminal 里执行,工作目录是工程根。

# 1. 依赖(本工程零三方依赖,这一步主要生成 oh_modules 骨架)
ohpm install

# 2. 构建 debug HAP
hvigorw assembleHap --mode module -p product=default -p buildMode=debug

# 3. 查看产物
ls entry/build/default/outputs/default/

# 4. 装到鸿蒙PC 设备(2in1 形态)
hdc install -r entry/build/default/outputs/default/entry-default-signed.hap

# 5. 启动,观察画布重绘行为
hdc shell aa start -b com.deciphr.faultlab -a EntryAbility

踩坑记录按「症状 → 原因 → 处置」写,每条都是这套工程上真实遇到过的:

  1. deviceTypes 只写 2in1 后,模拟器列表里找不到设备。 原因是用手机 / 平板镜像启动的模拟器不接受 2in1 应用。处置:用 2in1 形态的模拟器或真机,hdc list targets 确认目标在线后再 install。
  2. compatibleSdkVersion 写 26 编译报错。 从 API 26 起该字段必须写三段式 26.0.0,targetSdkVersion 同理。
  3. Canvas 首次进页面是空白。 不是 draw() 没执行,而是 onReady 早于布局完成,此时 ctx.width 为 0,clearRect(0,0,0,0) 加一次空绘制,什么也看不见。处置:onReady 里先判断宽度,或用本文第六章的 onAreaChange 兜底。
  4. 切换档案后画布不更新,点一下才出现。 即第六章那个缺 @Watch 的缺陷,不是渲染 bug,是刷新链路没接线。
  5. @Prop 装饰的对象改了内部字段,子组件不刷新。 ArkUI 的观察是浅层的,对象字段变更不会穿透。处置:改完字段后替换数组引用,或把对象改成 @Observed + @ObjectLink 的深层观察组合。
  6. ForEach 用文案当 key,改一个错别字整列闪一下。 key 必须是稳定且唯一的业务 id;本工程档案行用 f.id、页签用 k 都是对的,Postmortem 里用整行文本 (ln: string) => ln 当 key 是隐患,同一份报告里出现两行相同文案就会撞 key。
  7. 页面销毁后 toast 还在弹。 缺 aboutToDisappear() 清理定时器,见第八章。
  8. build() 里写 const stat = ... 直接编译失败。 ArkTS 的 build() 只允许 UI 描述语法,派生值必须在数据层算好或放进成员方法,但成员方法也别在 build() 里做 O(n) 遍历。
  9. 窗口拉到很窄时右侧内容被挤成一条。 左侧 railWidth 是固定 264 vp,右侧 layoutWeight(1) 会被压到接近 0。桌面应用的常规做法是按窗口宽度做断点,窄于阈值时把左侧收成图标栏;本工程尚未实现,是已知的形态适配欠账。
  10. 同一个 bundleName 反复装不同工程会失败。 调试签名与 bundleName 绑定,多工程复用同一个包名时,先 hdc uninstall com.deciphr.faultlab 再装,否则会报版本或签名冲突。

十二、小结

回到文章开头那个痛点:错误码看得见,但没人能说清它为什么复发、改哪行能让它不再出现。本文给出的是一个可落地的形状,而不是一句口号:

报错排查靠的是把错误码还原成「时间戳 + 通道 + 证据 + 权重」的四元信号序列,再从末端往前推,让「谁先到 1.0」和「疑点帧在业务层还是框架层」这两个问题一次问清。性能优化在鸿蒙PC 上不是一个独立话题,它和缺陷治理共用同一套敌人:Canvas 的重绘时机没接线、派生值在 build() 里现算四次、数组元素改了字段却没替换引用、定时器没在页面销毁时回收——这些问题的共同点都是「隐式」,而隐式在桌面常驻、窗口可变、hover 高频的环境里会被放大成用户能感知的迟滞与失灵。方案选型治理则要求先把词用准:本工程用的是 ArkUI 原生声明式 UI 框架,不是 ArkUI-X,也没有跨平台框架运行时;至于要不要引入跨平台框架,分水岭是「形态耦合度」——离开 2in1 桌面就不成立的工具,用原生;弱耦合的业务界面,用框架;纯展示内容,连框架都不必。

最后留一条可以立刻执行的建议:下一次你的排查工具里出现「点了没反应」,先别怀疑渲染管线,先去数一数这个状态有没有真的被替换过引用。 本文第八章那颗定时炸弹,就是从一个 return 少了一行复位开始的。

工程源码托管在 AtomGit,按第十一章的清单可以完整复现本文所有截图与修复。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐