把 Thorium Browser 搬到鸿蒙 PC 上,最先要回答的问题是:这个壳到底是一个浏览器,还是一个用来练浏览工作流的演示程序。答案在源码的第一行注释里就写死了——本壳不包含 Chromium 内核,不发任何网络请求,页面全部来自随包发布的离线副本。正因为如此,它才有机会做成一个真正可审查的工程:主进程只负责窗口、文件与路径纪律,渲染进程只负责把值摆进面板,所有判断都收敛到九个纯函数引擎里,任何一个面板的错误都能追到某一个函数的某一个分支上。

这篇记录的是完整适配过程。从工程骨架与 SDK 声明开始,到路径纪律的六道闸门、地址解析的分段与风险分级、标签前进后退的双栈、书签的 Netscape HTML 往返、历史记录的区间筛选、确定性下载台账的速率推导,再到设置单一来源与四格式报告的同源组装。文中出现的每一个数字,无论是文件行数、产物字节还是日志里的告警条数,都是从这一份工程里量出来的;发现的十个缺陷也都在源码里能指出具体位置。

欢迎加入开源鸿蒙 PC 社区:https://harmonypc.csdn.net/

欢迎在 PC 社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper

AtomGit 仓库地址:https://atomgit.com/OpenHarmonyPCDeveloper/ohos_Thorium

说明:文中代码包含源码节选;省略标记以注释表示,未展示完整函数、对象或条件分支的片段需要结合原始上下文阅读,不能独立运行。

一、技术架构分析

1.1 主进程的四件事与九个通道

main.js 一共 380 行、13361 字节,文件头的注释把职责范围划得很清楚:主进程只做四件事——开窗口、读写文件、守住路径、应答 IPC。它不持有标签页,不持有书签,不持有历史,也不持有下载台账。任何业务状态的真相都在渲染进程的 S 对象里,主进程只是被叫来干活。

这条边界带来的直接好处是主进程可以被彻底审查。打开 main.js 从上往下看,除了窗口创建和九个 IPC 处理器,没有第三类代码。九个通道分别是 app:info、bookmarks:open、bookmarks:save、history:open、history:save、report:save、settings:save、clip:write、shell:reveal,全部用 ipcMain.handle 注册,全部返回形如 success 加 error 的统一结构,渲染层只需要判 success 就能决定提示什么。

六个上限常量集中在文件顶部,都是硬上限,不读配置文件也不读环境变量:

常量值约束对象
WINDOW_TITLEThorium Browser窗口标题
MAX_TABS32标签页数
MAX_BOOKMARKS500书签条数
MAX_HISTORY500历史条数
MAX_DOWNLOADS64下载任务数
MAX_DATA_BYTES4194304导入文件字节数
MAX_REPORT_BYTES8388608导出报告字节数

app:info 这个通道值得单独说。它把 limits 的六项和 unsupported 的四条一起交给渲染层,unsupported 的四条是:不包含 Chromium 内核、不做 TLS 与证书链与 DNS 解析、下载是确定性模拟而非真实传输、不安装也不执行扩展。这四条不是免责声明,而是渲染层渲染文案的数据源——浏览器面板里那句「壳不访问互联网,只有 *.thorium.local 下的页面可以显示」,就是渲染层根据这四条的存在与否拼出来的。把限制做成数据而不是散落的字符串,是这套代码里最有价值的一个决定。

1.2 渲染层的铁律与 CSP 的呼应

index.html 的第 7 行挂着一条九指令的 CSP:

default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:;
connect-src 'none'; object-src 'none'; frame-src 'none'; base-uri 'none'; form-action 'none'

其中 connect-src 取 none 是这条策略的核心。它意味着页面里的 fetch、XMLHttpRequest、WebSocket、EventSource 全部被浏览器拦死,连自检嗅探都发不出去。这样一来,「不发任何网络请求」这句话就不需要靠代码自觉来保证,而是由平台的策略引擎强制。环境面板里那一格「网络访问 禁止(connect-src none)」正是把这条策略翻译成了人话,让人看得见约束从哪来。

renderer.js 一共 1578 行、60325 字节,文件头列了五项平台约束:不弹系统对话框、不用原生下拉框、不拼 HTML 字符串、不碰元素 style、不用帧回调。这五条在全文都能对上号:

  • 不弹系统对话框:保存与打开走的是主进程的 showSaveDialog 与 showOpenDialog,渲染层只收到一个路径字符串。
  • 不用原生下拉框:settings 面板的四组枚举全部渲染成芯片按钮,用的是 chip 函数,没有任何 select 元素。
  • 不拼 HTML 字符串:DOM 小工具只有 el、kv、chip、itemLine 四个,一律用 createElement 加 textContent。全文搜不到一处 innerHTML。
  • 不碰元素 style:切换面板和状态靠改 className,比如 switchPanel 里给面板加 active,notice 里给状态条加 err 或 ok。
  • 不用帧回调:没有任何 requestAnimationFrame,唯一的时间驱动是下载推进的 setInterval。

八个面板挂在同一个工作区里,靠 PANELS 数组统一驱动:浏览器、标签页、书签、历史记录、下载、设置、校验与报告、环境与限制。每个面板一个 section,一个 panel 类,切换时只改 className 和滚动位置,DOM 结构不动。这种做法在桌面端特别稳——面板切换不会引起重排风暴,也不会丢掉输入框里正在编辑的文本。

1.3 九个引擎的拓扑序

业务逻辑全在 engines 目录下的九个文件里,总计 2190 行、78965 字节,占 app 目录全量 14 个文件 5329 行、189078 字节的 41.10% 与 41.76%。

引擎行数字节职责
br-util.js2276285数值、时间、哈希、格式化工具
br-url.js2869703地址解析、主机校验、风险分级
br-settings.js2237591设置默认值、枚举、预设、校验、序列化
br-sites.js1658204六页离线副本与六个快捷入口
br-tabs.js2076527标签创建、导航、双栈、钉住、静音
br-bookmarks.js2639271书签增删改查与 Netscape HTML 往返
br-history.js2177700历史合并、检索、区间筛选、按站点统计
br-downloads.js2628446下载任务六态机与速率推导
br-report.js34015238四格式报告的组装

index.html 底部的九个 script 标签顺序就是依赖的拓扑序:util 在最前,report 在最后,renderer 压轴。这个顺序不是随意排的——br-url 用到 util 的 clamp 和 hash32,br-downloads 用到 br-url 的 parse,br-report 用到前面八个里的六个。由于全部脚本都是普通 script 而非 module,加载时同步执行,全局对象在解析期就已就位,所以后面的引擎可以直接引用前面的引擎,不需要任何延迟初始化或注入。

依赖方向严格单向,没有回指。把九个文件按依赖排出来是一条干净的链:util 无依赖;url 依赖 util;settings 依赖 util 与 url;sites 依赖 url;tabs 依赖 util 与 url;bookmarks 依赖 util 与 url;history 依赖 util 与 url;downloads 依赖 util 与 url;report 依赖 util 与 url 与 settings 与 tabs 与 bookmarks 与 history 与 downloads。report 之所以排最后,就是因为它要横向汇总六个引擎的结果,但它自己不被任何人依赖,闭环干净。

renderer.js 用 eng 函数把九个引擎取到九个局部变量里,取不到就置 null。这不是防御性编程的花架子,而是让「引擎缺失」这件事在环境面板里能被直接点名——selfTest 会逐个数出装上了几项、共几项,环境面板显示九分之九才算健康。

二、环境准备

2.1 工程骨架与 SDK 声明

工程的根目录下是两个模块加两份说明文档。两个模块是 electron 与 web_engine:electron 是 entry 类型的壳模块,负责承载应用能力;web_engine 是共享库模块,装的是 Electron 的 native 层与 ArkTS 适配层。ohos_hap 下的 build-profile.json5 把这件事说得很直白:

{
  "app": {
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.5(17)",
        "compatibleSdkVersionStage": "release",
        "runtimeOS": "HarmonyOS",
        "buildOption": {
          "nativeLib": {
            "collectAllLibs": true
          }
        }
      }
    ],
    "buildModeSet": [
      { "name": "debug" },
      { "name": "release" }
    ]
  },
  "modules": [
    {
      "name": "electron",
      "srcPath": "./electron",
      "targets": [{ "name": "default", "applyToProducts": ["default"] }]
    },
    {
      "name": "web_engine",
      "srcPath": "./web_engine"
    }
  ]
}

三处需要留意。第一,compatibleSdkVersion 写的是 5.0.5(17),即 API 17。这个数字决定了两件事:包能装到哪些设备上,以及编译期能用哪些接口。写成字符串加括号的形式是 hvigor 认识的格式,括号里的 17 才是真正的 API 号。

第二,collectAllLibs 取 true。这一项的作用是把依赖树里所有 so 都收进产物,而不是只收被直接引用的那几个。Electron 壳的 native 层是一整组互相依赖的库,漏一个就会在真机上打不开窗口,所以这一项对这类工程是必需的,不是可选项。

第三,整份 build-profile.json5 里没有 targetSdkVersion。这不是笔误,而是这一批工程的共同现状:只声明了兼容版本,没声明目标版本。构建日志里因此留下了四条同样的告警:

The project has not explicitly set the 'targetSdkVersion' version at build-profile.json5.
It is recommended to configure it.

打包信息里能反推出来实际生效的目标版本是 20,因为 pack.info 的 apiVersion 段落写着 compatible 17、target 20、releaseType Release。也就是说 SDK 用了默认值把包打出来了,但这个默认值不会永久稳定——上架前把 targetSdkVersion 显式写成 20,是必须补的一步。

另外要提醒的是 signingConfigs 段落。它记录的是本机的调试签名材料,里面有三个 C:\Users\ws199.ohos\config\ 开头的绝对路径,以及两个十六进制串形式的加密口令。这份文件绝不能原样进仓库,替换成自己的签名材料是导出工程后的第一件事。四期的那批工程里几乎每一份都带着同样的本机路径,说明这批文件是从同一台机器上导出的模板,需要逐个清理。

2.2 应用信息与清单

AppScope/app.json5 定义应用身份:

{
  "app": {
    "bundleName": "com.huawei.ohos_electron",
    "vendor": "example",
    "versionCode": 1000000,
    "versionName": "1.0.0",
    "icon": "$media:app_icon",
    "label": "$string:app_name",
    "configuration": "$profile:configuration",
    "multiAppMode": { "multiAppModeType": "multiInstance", "maxCount": 1 }
  }
}

三处是上架前必改的:bundleName 用的是 com.huawei.ohos_electron,这是模板包名,与 Thorium Browser 这个产品没有关系,申请到正式包名后要整体替换;vendor 写的是 example;AppScope/resources/base/element/string.json 里 app_name 的值是 Electron,桌面图标下面显示的就是这个名称。versionCode 1000000 与 versionName 1.0.0 是可以保留的起点,后续每次提审加一。

multiAppMode 这一段取的是 multiInstance、maxCount 1,含义是允许应用以多实例方式启动但最多一个实例。对一个浏览工作台来说这是合理的:单窗口、单实例、不允许多开抢夺同一个配置文件。

打包后的 pack.info 一共 752 字节,把运行期的形态交代得很完整:

{"summary":{"app":{"bundleName":"com.huawei.ohos_electron","bundleType":"app",
"version":{"code":1000000,"name":"1.0.0"}}},"modules":[{"mainAbility":"EntryAbility",
"deviceType":["2in1","tablet"],"abilities":[{"name":"EntryAbility","label":"$string:EntryAbility_label"},
{"name":"BrowserAbility"},{"name":"StatelessAbility","label":"$string:StatelessAbility_label"}],
"extensionAbilities":[{"name":"StatusBarEntryAbility"},{"name":"BrowserEmbeddedAbility"}],
"distro":{"moduleType":"entry","installationFree":false,"deliveryWithInstall":true,
"moduleName":"electron"},"apiVersion":{"compatible":17,"releaseType":"Release","target":20}}]}

三个 ability 加两个 extensionAbility,主 ability 是 EntryAbility,设备形态是 2in1 与 tablet 两种。这三个 ability 是 Electron 壳的固定配置:EntryAbility 起窗口,BrowserAbility 供内嵌浏览场景调用,StatelessAbility 提供无状态入口;两个 extensionAbility 分别对接状态栏与嵌入式浏览。对纯离线工作台来说,BrowserAbility 与两个 extensionAbility 实际并不参与业务流程,但它们在清单里存在,会一并接受审核。

两份 JSON5 里还存在若干对象末尾多余逗号。逐个文件数下来一共十处:electron 的 build-profile.json5 三处、web_engine 的 build-profile.json5 一处、electron 的 module.json5 三处、web_engine 的 module.json5 一处、electron 的 oh-package.json5 一处、web_engine 的 oh-package.json5 一处。JSON5 标准允许尾逗号,hvigor 也接受,所以这些逗号不会引起构建失败,但它们会破坏 JSON 严格解析的兼容性——一旦用 JSON.parse 去读这些文件,全部会抛异常。把工程配置同时喂给别的工具链时,删掉这十个逗号是成本最低的兼容措施。

2.3 环境自检与限制面板

这套应用给自己准备了两层自检,一层在引擎里,一层在面板上。

引擎层的自检是 selfTest,逐项跑九个引擎的核心函数,每通过一项就给徽章加一分:util 做一次数值收敛,url 解析一个地址并检查风险数组,settings 取默认值并校验,sites 数页面数量,tabs 建一个标签并推一次栈,bookmarks 加一条再删一条,history 加一条并检索,downloads 建一个任务并推进一秒,report 用最小上下文生成一份文本。九项全过,徽章显示九分之九;缺一项,就少一分并指出是哪一项。这种自检的意义不在于发现代码 bug,而在于快速判断「文件是不是全部就位」——引擎文件被截断、路径写错、加载顺序打乱,都会在这里立刻暴露。

面板层是环境与限制,一共十二格,展示的是运行环境而不是代码自检。包括应用信息、模块信息、设备形态、SDK 版本、路径信息、上限常量、网络访问这一格写着「禁止(connect-src none)」。第十二格的作用是把 1.2 节那条 CSP 兑现成人能读的结论——策略里写了什么,面板上就显示什么,两者不会互相说谎。

启动流程也是按这两个自检来编排的。renderer 的 boot 先读设置默认值,按 startPage 的三种取值决定初始标签:打开起始页、恢复上次会话、打开空白页。然后拿 app:info 的返回填 S.info,再调 renderEnv 与 renderDerived 把整屏刷一遍,最后用一句话给出就绪提示,把离线页面数、标签数、书签数一次报出来。这句话里的数字全部来自引擎统计而不是硬编码,所以第一次启动时它显示的书签数就是 br-bookmarks 的 sample 条数,下载数是三——三个预置的已完成任务,正好能让下载面板一进去就有内容可看。

三、核心适配流程

3.1 路径纪律与九个通道

Electron 壳最容易出事的地方就是文件路径。渲染进程递上来一个路径,主进程如果直接拿它去写文件,就等于把整个磁盘交给了页面。main.js 用六个函数把这件事管死了,逻辑是一条链:

function fwd(p) { return String(p == null ? '' : p).replace(/\\/g, '/'); }

function normForCompare(p) {
  var s = fwd(p);
  if (s.length > 1 && /\/$/.test(s)) s = s.slice(0, -1);
  return process.platform === 'win32' ? s.toLowerCase() : s;
}

function isInside(child, parent) {
  var c = normForCompare(child), p = normForCompare(parent);
  if (!c || !p) return false;
  return c === p || c.indexOf(p + '/') === 0;
}

fwd 把反斜杠统一成正斜杠,后面的比较就不再受路径分隔符影响。normForCompare 去掉末尾多余的斜杠,Windows 下再转小写——这两步合起来解决的是「同一个目录的不同写法」。真正关键的是 isInside 的第二项:它比的是 p 加一个斜杠再当前缀,而不是光比 p。多这一个斜杠,就挡掉了 /data/app/ab 被误判为 /data/app/a 的子路径这一类越界。

isAllowed 在 isInside 之上再包一层,先把待检路径 path.resolve 成绝对路径,再逐个和白名单根比对;guard 是 isAllowed 的断言版,不在白名单里就抛一个带 EGUARD 码的错误;rememberRoot 则是往白名单里加根,加之前先用 normForCompare 去重,避免白名单无限膨胀。四个函数串起来就是一句规则:只有对话框亲手选过、或者应用自己启动时登记过的目录,才允许读写。

白名单的初始内容只有两个:whenReady 里把 app.getPath 给出的 userData 和 __dirname 登记进去。其余目录全部靠对话框临时授权——saveText 在拿到对话框返回的路径后立刻 rememberRoot 该路径的父目录,openText 同样在读到路径后立刻 rememberRoot。所以白名单不是配置出来的,是用户点出来的。

guard 在九个通道里只有一处直接调用:shell:reveal,也就是把文件所在目录交给系统文件管理器打开。文件读写通道反而是靠 saveText 与 openText 内部绕开 guard 的,因为它们拿到的路径本来就来自对话框,天然在白名单里。这个取舍值得记下来——校验放在「路径来源不可信」的地方,而不是无脑给每个通道加一层 guard。

错误文案是一张十二项的对照表:EACCES、EPERM、ENOENT、EEXIST、EISDIR、ENOTDIR、ENOSPC、EMFILE、EBUSY、EROFS 十个系统码,加上本工程的 EGUARD 与 EBADJSON 两个自造码。errText 的取值顺序是三级:先查表,查不到就看消息里有没有汉字,有就直接用,最后才兜底成「系统调用失败(错误码 X)」。这三级的用意写在注释里:状态条只展示中文,英文系统原文与绝对路径不外泄。一个文件读写失败,状态条上不该出现 C:\Users 开头的半截路径。

落盘函数 saveText 的步骤是有序的:先算 UTF-8 字节数并比上限,超了就直接返回而不弹对话框;再弹保存对话框;拿到路径后校正一次后缀(用户可能手打错了扩展名);然后 rememberRoot 父目录、递归建目录、写文件。先把明显无效的请求拒掉再弹窗,是为了不让用户白点一次取消。

读取函数 openText 的顺序反过来:先弹对话框,拿到路径后立刻 rememberRoot,再用 statSync 看是不是普通文件、是不是零字节、有没有超过四兆。先 stat 再 read 的顺序不能调换,一个几 G 的文件如果先读了再判断,进程已经被拖死了。

IPC 的统一包装只有十四行,但里面有一句关键的注释:

function handle(channel, fn) {
  ipcMain.handle(channel, function (event, req) {
    var fail = function (e) {
      return { success: false, error: errText(e), code: (e && e.code) || '' };
    };
    try {
      var out = fn(req || {});
      /* async 处理器里的 throw 会变成 rejected promise,同步 try/catch 抓不到 */
      if (out && typeof out.then === 'function') return out.then(null, fail);
      return out;
    } catch (e) {
      return fail(e);
    }
  });
}

try/catch 只能抓住同步抛出。异步函数里的 throw 会变成一个 rejected promise,try/catch 完全看不见,最后变成一个没人处理的 rejection 静默丢掉——界面上什么都不会提示,用户只看到按钮点了没反应。这一行 out.then(null, fail) 就是把这条缝补上。凡是写 Electron 主进程的,这一处都该抄。

3.2 地址解析与风险分级

br-url.js 是全部引擎里被复用最多的一份。浏览器面板用它渲染解析结果,书签校验用它判断地址合法性,历史记录用它决定是否写入,下载台账用它决定任务能否创建,报告用它统计错误数。一个解析函数撑起五个面板,前提是它返回的东西足够全。

parse 的分段顺序是照 RFC 里地址的结构来的:先切协议,再切片段,再切查询,最后切路径与主机。切的顺序有讲究——片段符号可能出现在查询串里,查询符号可能出现在路径里,所以必须从右往左按优先级切,先把最靠后的片段切走。

var m = /^([A-Za-z][A-Za-z0-9+.-]*):\/\//.exec(raw);
var scheme = m ? m[1].toLowerCase() : '';
var body = m ? raw.slice(m[0].length) : raw;

if (m && scheme !== 'http' && scheme !== 'https') {
  out.kind = 'blocked';
  out.text = '出于安全策略,只允许 http 与 https 地址';
  out.risks.push({ level: 'err', text: '禁止的协议:' + scheme + '://' });
  return out;
}

协议白名单是硬性的,file、javascript、data、ftp 一律 blocked 并带一条 err 级风险。这条规则在一台离线的演示壳里尤其重要:file 协议一旦放行,地址栏就成了文件系统浏览器。

没有协议前缀时走另一条路。looksLikeHost 判断这串东西像不像主机名,像就补 https 继续解析,不像就整串当成搜索词返回 kind 为 search。这个分支让地址栏同时兼了搜索框的职能,而搜索词的拼装交给设置里的四项模板之一完成。

风险分级是这份引擎的核心设计。risk 数组里每一条带 level 字段,取值只有三档:err、warn、ok。判定规则一共八条,全部可以对照代码逐条验证:

情形级别判定依据
地址长度超过 2048errMAX_LEN 常量
协议不在白名单err协议正则的结果不属于 http 或 https
地址含账号密码errauthority 里出现 at 符号
缺少主机名err切分后 host 为空
主机名格式不合法errvalidHostname 返回 false
端口非法或 IPv6 缺右括号err端口不在 1 到 65535 之间
直接用 IP 访问warnvalidIpv4 命中或 IPv6 分支
国际化域名warn主机里出现非 ASCII 字符
明文 HTTPwarnscheme 为 http
使用非默认端口warn端口字段非空
路径含上跳片段warn路径里出现两个点组成的段
常规 HTTPSok非 IP、非本地、https、无端口

最后一条的写法很有意思:只有在四条否定条件同时成立时才补一条 ok 级的「常规 HTTPS 地址,未发现明显风险」。所以浏览器面板上的风险清单永远不是空的——要么有真实风险,要么有一条明确的通过结论。这种「不给空白、只给结论」的设计,让界面上那句「风险提示 0 条」永远不出现,取而代之的是「风险 1 条(通过)」这样的诚实表述。

主机校验分三层。validIpv4 严格到四条八位组必须都是纯数字、数值不超过 255、并且禁止前导零——192.168.001.1 这种写法会被判成非法主机名而不是合法 IP,因为前导零的 IPv4 在不同解析器里含义不一,是历史上的地址混淆来源。validHostname 限制总长 253、单段 63、不允许空格与下划线、不允许连字符开头结尾,但放开了非 ASCII 字符给国际化域名用。

第三层是 isLocalHost,判定 localhost、点 local 结尾,以及 127、10、192.168、172.16 到 172.31 四个私网段。这个函数的意图很清楚:把「访问的是本地或内网」这件事和「访问的是公网 IP」区分开,前者不该报证书风险。但实际调用链上没有接上——parse 里判断本地用的是另一段内联正则:

} else if (bareHost === 'localhost' || /\.local$/i.test(bareHost)) {
  out.isLocal = true;
}

这段只认 localhost 和点 local 结尾两个条件,私网 IP 完全进不来;而且它挂在 validIpv4 的 else if 后面,192.168.1.1 这种地址早在上一支就命中 isIp 并 return 掉风险分支了。结果是 isLocalHost 在全工程零调用,私网地址的 isLocal 恒为 false。这个缺陷留在第四章展开。

3.3 标签栈与前进后退

br-tabs 的标签对象只有七个字段:id、url、title、back、fwd、pinned、muted。前进后退全部靠两条普通数组实现,没有游标、没有索引指针,一次导航只做三件事:把当前地址压进 back、清空 fwd、替换地址。

function navigate(list, id, url, title) {
  var out = clone(list || []);
  var tab = find(out, id);
  if (!tab) return { list: out, tab: null, error: '标签不存在,无法导航' };
  tab.back.push({ url: tab.url, title: tab.title });
  if (tab.back.length > MAX_STACK) tab.back = tab.back.slice(tab.back.length - MAX_STACK);
  tab.fwd = [];
  tab.url = String(url || '');
  tab.title = String(title || tab.url || '新标签页');
  return { list: out, tab: tab, error: '' };
}

那次清空 fwd 是浏览器的标准语义:从后退了两步的位置再导航到新地址,原来的前进历史就作废了。不写这一行,用户会发现前进按钮能点,点下去跳到一个不该存在的历史分支。

back 与 forward 是对称的两段代码,各三步:先压栈、再弹栈、最后换地址。back 把当前地址压进 fwd 再从 back 弹出来,forward 反过来。两段都是先压后弹,顺序如果反过来,同一个地址会被弹掉又压回去,栈深度立刻失衡。

两段还有个共同点:栈空时返回 moved 为 false 但 error 为空字符串。这是刻意的——栈空不是错误,用户点了一个不该能点的按钮才是。渲染层据此把按钮的 disabled 状态跟着栈深度走,栈一空按钮就暗下去,用户点不到;就算误触,也因为 error 为空而不会弹出红字提示。状态前置比事后报错好,这一点在桌面端尤其明显。

MAX_STACK 是 50,超了就从头裁掉最老的记录,保留最近 50 步。双栈合起来一个标签最多记 100 个地址,乘以 32 个标签的上限,最坏情况下内存里存着 3200 条地址记录,每条带 url 与 title 两个字符串——这个量级完全可以接受,这也是为什么作者敢用无上限的数组而不是环形缓冲。

钉住与静音是纯翻转,move 是相邻交换并返回新索引。四个函数都不涉及 URL 解析,所以在依赖图里它们只用到 util 的 clone 与 int。

关闭标签时引擎返回的东西值得注意:

function close(list, id, opts) {
  var out = clone(list || []);
  var i = indexOf(out, id);
  if (i < 0) return { list: out, closed: null, error: '标签不存在,可能已经关闭' };
  var closed = out.splice(i, 1)[0];
  var limit = U.int((opts || {}).closedLimit, MAX_CLOSED, 1, 50);
  return { list: out, closed: closed, error: '', closedLimit: limit };
}

它把被关掉的标签整个交还给调用方,自己不维护任何历史列表。这符合纯函数引擎的分工——引擎不该有跨调用的记忆。最近关闭的台账因此落在渲染层的 S.closed 数组上:关闭时 unshift 进去并裁剪到十项,恢复时取第一项、shift 出去、再走一次 open 把标签重新建起来。界面上那个「最近关闭」徽章与恢复按钮读的就是这十项。

分层是对的,但有一处小瑕疵:引擎把 limit 算好并通过 closedLimit 返回,渲染层却直接拿常量 MAX_CLOSED 去做裁剪比较,返回的 closedLimit 全程没被读过。今天两边都是 10,看不出问题;哪天调用方传了一个不同的 closedLimit,引擎算的和渲染层裁的就会是两个数。这种「参数算出来了却没人用」的地方,是以后最难查的一类不一致。

3.4 书签 HTML 往返与历史筛选

书签的存储格式选了 Netscape Bookmark File,也就是所有浏览器都认的那个老格式。这个选择不是怀旧:它让导出的文件能直接拖进任何一款浏览器里导入,双向都通——既能带走,也能带来。

导出侧生成的是标准的嵌套结构,外层文件头、中间 DL 列表、每条书签一个 A 标签加时间戳属性。导入侧的 fromHtml 逐行扫,遇到 H3 就记下当前文件夹名,遇到 A 就取地址与标题。

这条路线有一个真实的坑:folder 变量记的只是「最近一次遇到的 H3」,遇到 DL 闭合时没有回退。Netscape 格式是有层级的,一个收藏夹列表里可以套另一个列表,闭合内层之后,后面的书签本该回到外层文件夹名下,但由于没有层级栈,它们会一直挂在内层最后一个 H3 上。单层导出再导入不会有问题,一旦导入的是别的浏览器导出的多层级文件,目录归属就会整体串位。修法不复杂——用数组当栈,遇 H3 入栈、遇闭合出栈——但这属于「只有拿真文件试才会发现」的一类缺陷,自造样本测不出来。

书签的容量上限是 500,超了 add 会直接拒绝并在错误文案里带上实际上限值。重复地址的处理是拒绝而不是去重:check 会拿待写入的地址和整张表逐个小写后比对,编辑已有条目时用 editingId 把自身排除掉,一旦命中就回「书签里已经有这个地址」。这个做法比静默去重诚实——用户以为添加成功了,实际上条数没变,这种沉默的失败最难排查。同一项 check 里还卡了三条长度限制:名称不超 64 个字符、文件夹名不超 32 个字符,地址必须能过 br-url 的 parse。

历史记录那边是另一种思路。它的核心不是增删改,而是三件事:合并、检索、区间筛选。

合并窗口是六万毫秒,也就是一分钟。命中合并的判断很朴素:

if (out.length) {
  var head = out[0];
  if (String(head.url).toLowerCase() === p.url.toLowerCase() && Math.abs(now - head.visitedAt) < MERGE_WINDOW) {
    out[0] = { id: head.id, url: p.url, title: title, visitedAt: now };
    return { list: out, added: false, merged: true, skipped: false, error: '' };
  }
}

只比较列表头部,且两个地址要小写后完全相等,时间差在一分钟以内。命中就只更新时间、保留原 id、条数不变。这个策略的效果是:在一个页面里反复点刷新、反复跳回同一地址,历史里不会堆出一长串一模一样的行。比较只做头部而不做全表,是为了让添加操作保持常数级——历史一旦到 500 条,全表扫描每次导航都要跑一遍。

区间筛选有四个档位:今天、最近 7 天、最近 30 天、全部。今天这一档的实现值得单独说,它没有用「当前时间减 24 小时」这种偷懒写法,而是重算了一次本地零点:

if (range === 'today') {
  return new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime();
}

用年月日三个分量重建 Date,得到的就是本机时区下当天的零点。用减法算出来的是「过去 24 小时」,凌晨两点打开应用时两者能差出小半天——用户选「今天」看到昨天下午的记录,这种事在日志类应用里是高频投诉点。

按站点统计用 hostOf 把地址收敛到主机,计数后按次数降序、同次数按主机名字典序排。加那一次字典序比较是为了让结果稳定:只按次数排,两条同频的主机在不同引擎里的相对顺序可能不一样,导出的报告就会出现「同样的数据两次生成不一样」的怪现象。

历史还有一处 JSON 往返的问题:fromJson 在按时间倒序排完之后才依次赋 id,排序改变的是数组顺序,而 id 是按排序前的顺序给的,所以导入之后 id 与位置不再对应。功能上不影响排序(排序靠 visitedAt,不靠 id),但界面上如果按序号显示「第几条」,就会看到 id 是乱序的。下一章把这一类问题汇总成表。

3.5 确定性下载台账

下载面板是这套应用里最容易被质疑「是不是假数据」的地方,所以它的设计必须能自证。三处设计撑起了这份可信度。

第一处是速率来源。每个任务的速率不是随机数,而是从地址算出来的:

function speedOf(url) {
  var h = U.hash32(String(url || ''));
  return 393216 + (h % 917504);
}

哈希取模 917504 再加 393216,结果落在 384 KB/s 到 1280 KB/s 之间。同样的地址在任何时候、任何机器上算出来的速率都一样。这一条把「随机数」的嫌疑彻底排掉了——如果界面上的数字每次打开都变,任何人都能判断这是假的;而同一个地址永远给同一个速率,说明这个数是从输入推出来的。

第二处是推进方式。引擎里没有定时器,只有 step 函数,它接收列表和当前时间,返回推进一秒后的新列表。定时器在渲染层,一秒调一次 step。这个分工让引擎完全可测:给定输入列表、给定时间戳,输出是确定的,不需要等、不需要 mock 时钟。

function step(list, opts) {
  var o = opts || {};
  var limit = Math.max(0, Number(o.limit) || 0);
  var now = Number(o.now) || 0;
  var advanced = 0;
  var completed = 0;
  var out = (list || []).map(function (t) {
    var x = U.copy(t);
    if (x.status === 'queued') x.status = 'running';
    if (x.status !== 'running') return x;
    var inc = x.speed;
    if (limit > 0 && inc > limit) inc = limit;
    x.done = Math.min(x.size, x.done + inc);
    advanced += 1;
    if (x.done >= x.size) {
      x.status = 'done';
      x.finishedAt = now;
      completed += 1;
    }
    return x;
  });
  return { list: out, advanced: advanced, completed: completed };
}

排队的任务在第一次 step 时转成运行,运行的任务按速率加字节,用 min 卡住不越过总量,到了就转成完成并记下完成时刻。限速就是在这一步截断:限速值大于零且小于速率时,用限速值替代速率。所以限速不会让任务变慢一点点,而是精确地按限速推进——选 1 MB/s 的任务,每秒就前进 1024 乘 1024 个字节。

第三处是「不写真实文件」。整个下载流程里没有任何一次 fs 调用,done 只是一个计数。界面上那句「任务是指针推进的模拟,每秒推进一次,不写真实文件」不是免责声明,是对实现的准确描述。

任务状态一共六种:queued、running、paused、done、failed、canceled。表面上六种状态的转移关系是清楚的,实际上四个动作函数里有一个写反了——这也是本文要指出的最严重的一个缺陷,本节先按下不表,第四章再把它拆开。

创建任务时的默认大小同样是从地址推出来的:最小值加上地址哈希对十二兆取模的结果,落在一 KB 到 12 MB 之间。名称从地址的最后一段取,取不到就退化成主机名加点。这两个推导让「新建任务」这个动作完全不需要用户填任何东西,也不会产生随机值。

3.6 设置单一来源与四格式报告

设置项一共 14 个键,全部集中在 br-settings 的 KEYS 数组里。「集中」这两个字是这套代码的规矩:默认值在 defaults,枚举候选在 OPTIONS 的四个分组里,预设档位在 PRESETS 的三档里,校验规则在 validate 里,序列化也只认这 14 个键。界面上的芯片按钮、报告里的事实条目、校验时的错误清单,三处读的都是同一份定义。

14 个键覆盖了六个维度:外观(主题、缩放)、启动(起始页)、搜索(引擎与模板)、隐私(历史开关、保留天数、清除确认)、容量(标签、书签、历史、下载四个上限)、界面(状态条、侧栏密度)。每个键在 OPTIONS 里都有对应的中文标签,所以界面上任何一个芯片都能直接取到名字,不需要写映射表。

预设三档是「轻量」「均衡」「严格」。它们不是三套独立的默认值,而是三组对上面 14 个键的覆盖。applyPreset 的作用就是把某一档的覆盖项合并到当前值上,其余键保持不变。这个设计让预设在界面上表现为一次批量修改,而不是一次重置——用户改了三个键之后套一个预设,改动的只有预设涉及的那几个。

validate 一共给出六条错误与三条警告。错误是硬性的:值不在候选范围内、数值超界、天数不合法之类;警告是软性的提醒,比如关掉历史开关却选了「恢复上次会话」,或者上限设得过高。渲染层把错误处理成拒绝保存,把警告处理成黄色提示但允许保存。这个区分很重要——把可接受的可疑配置拦下来,用户会认为软件在挑刺。

序列化有两个方向,存储用的是带缩进的 JSON,读取走的是 parse。parse 的返回结构里有四个字段:values、unknown、errors 以及推导出的默认值。未知键会被单独收进一个数组:

if (KEYS.indexOf(k) < 0) out.unknown.push({ key: k, value: data[k] });

紧挨着的注释写着「未知键原样保留:别人加的字段不该在保存时消失」。意图很清楚:配置文件可能被别的版本、别的工具改过,多出来的字段在读的时候要记住、在写的时候要原样写回去。但 serialize 只遍历了那 14 个键,unknown 数组从头到尾没有任何一处被读走。所以这段承诺在执行层面是落空的——读进来时记住了,保存时又丢了。第四章会单独展开。

报告是这套应用的出口。它把前面八个引擎的结果汇总成一份可带走的事实清单,支持四种格式:Markdown、JSON、CSV、纯文本。

四种格式的源头完全一致。facts 函数把六组事实整理出来——概览、设置、标签页、书签、历史、下载,每组若干条,每条带名称、值、级别三个字段。limits 函数单独整理上限类信息,把设置里的偏好值与主进程给的硬上限并列出来,再合并一次校验结果。四种格式的渲染器都在这两组数据上工作,没有哪一种格式自己另外算一遍。

function build(format, ctx) {
  var f = facts(ctx);
  var l = limits(ctx);
  /* 此处省略其余实现 */
}

这个结构带来的效果是可验证的:同一时刻生成 Markdown 和 CSV,两边的「标签页数」必须是同一个数。如果哪一份是现场再算的,两个格式就不会一致,而这种不一致在评审时几乎无法解释。

四格式各有各的用途:Markdown 给人读,带六个小节的标题和一张能力边界表;JSON 给程序读,字段名固定;CSV 给表格读,中文表头,单元格里的逗号与引号会转义,行尾用 CRLF,整份文本不带 BOM——Excel 打开会显示乱码,但标准工具链读得对;纯文本给剪贴板,粘贴到哪里都还看得懂。

CSV 那一处不带 BOM 的选择值得留意。带 BOM 能让 Windows 上的 Excel 正确识别 UTF-8,代价是文件开头多三个不可见字节,很多解析器会把它们当成第一个表头的一部分。作者选了不带 BOM,等于选了工程正确性而不是桌面便捷性。这个取舍没有对错,但要在文档里说清楚,否则用户第一次用 Excel 打开就会来提问题。

四、鸿蒙稳定性适配

4.1 十个需要先处理的问题

把九个引擎与渲染层通读一遍,能指到具体位置的问题一共十个。它们的严重程度差很多:有的是让一个功能完全失效,有的只是命名或者参数没用上。但既然每个都能定位到具体函数,就应当在上架前逐个结清。

编号位置问题影响
D1br-downloads 的 resume先把任务改成 queued,再用 queued 当错误条件暂停的任务永远无法恢复
D2br-settings 的 serialize只写 14 个键,parse 收集的 unknown 无处使用未知键在保存时丢失
D3br-url 的 isLocalHost定义并导出但零调用,parse 用内联正则私网地址的本地判定恒为假
D4renderer 的 makeReport报告内时间戳与面板生成时刻各取一次时间两者可能差一秒
D5renderer 的 boot下载计时器的返回值未保存无法停止计时器
D6renderer 的 tickDownloads变量名表示名字,实际存的是计数阅读误导,易改错
D7br-history 的 fromJson排序后按新顺序赋 id导入后 id 与位置不对应
D8br-bookmarks 的 fromHtml文件夹只记最近一个标题,闭合不回退多层级导入目录串位
D9br-sites 的两处对象字面量末尾多余逗号严格 JSON 解析不兼容
D10br-tabs 的 close 与调用方引擎返回了上限值,调用方却用常量裁剪两处上限未来可能不一

这十条里,不影响运行的有两条。D9 是包能正常打出来的一条:JSON5 允许尾逗号,hvigor 也照单全收,它唯一的影响在别的工具链——任何用 JSON.parse 去读这两个文件的工具都会直接抛异常。修起来就是删两个逗号,没有理由不修。

D6 同样不影响运行:一行过滤取长度的结果被赋给了名为 names 的变量,names 里装的是一个数字,后面的三元判断用得也对,因为数字本来就是真假值。但它会误导下一个维护者——看到 names 会以为是个数组或字符串,于是想对它做映射或者再取一次长度,改出 bug 来。把名字改成 count 是一秒钟的事。

其余八条都是真问题。下面把最影响使用的三条拆开看。

4.2 三条典型缺陷的根因

第一条:resume 把成功当成失败。

下载面板上有个「继续」按钮,点了之后界面上根本不推进,只弹一句「任务已经在队列中,无需继续」。问题出在引擎里这一个函数:

function resume(list, id) {
  var out = (list || []).map(function (t) {
    if (t.id !== id) return t;
    if (t.status !== 'paused' && t.status !== 'failed') return t;
    var x = U.copy(t);
    x.status = 'queued';
    x.error = '';
    return x;
  });
  var t = find(out, id);
  if (!t) return { list: out, error: '任务不存在' };
  if (t.status === 'done') return { list: out, error: '任务已经完成,无需继续' };
  if (t.status === 'running') return { list: out, error: '任务正在下载,无需继续' };
  if (t.status === 'queued') return { list: out, error: '任务已经在队列中,无需继续' };
  return { list: out, error: '' };
}

把执行路径走一遍就看得很清楚。一个 paused 任务进来,第一段 map 把它改成 queued;第二段重新找出来的 t,拿到的是已经改过的那个副本,而不是原始任务。于是三行判断里的前两行永远不会命中(没人是 done 或 running),第三行必然命中——因为任务刚刚就是被改成 queued 的。最后那行「无错返回」是永远到不了头的死代码。

这个缺陷的可怕之处在于它是「自己把自己送进了错误分支」。同一个文件里的另外三个动作函数,判断方向都是反的,所以都是对的:

function retry(list, id) {
  /* 此处省略其余实现 */
  if (t.status !== 'queued') return { list: out, error: '只有失败或已取消的任务可以重试' };
  return { list: out, error: '' };
}

function cancel(list, id) {
  /* 此处省略其余实现 */
  if (t.status !== 'canceled') return { list: out, error: '已完成的任务不能取消' };
  return { list: out, error: '' };
}

retry 写的是「如果不是 queued 就报错」——它先把失败任务改成 queued,然后确认它确实是 queued,确认通过就返回成功。cancel 同理。只有 resume 写成了「如果是 queued 就报错」,把前置条件当成了后置条件。

修法有两种。最简单的是把最后一行改成否定式,和 retry 保持一致:如果状态不是 queued 就报错,否则返回成功。更彻底一点的做法是让 map 把「改动前的状态」先存下来,后面的判断全基于旧状态——这样逻辑不再依赖于「先改后判」这个容易写反的模式。两种都行,关键是同一文件内四个函数必须用同一种模式,否则下一次改动还是会踩到。

这个缺陷还有一个放大因素:渲染层的 dlAction 遇到 error 就直接 return,不会去分辨错误等级。所以用户看到的是「点了继续,界面什么也没发生」,而不是「任务已恢复但因为有错所以没动」。一个错误的错误文案,把一个本可以被发现的逻辑 bug 包装成了「好像不能用」的模糊感受。

第二条:承诺保留未知键,实际丢掉了。

br-settings 的 parse 里有这么一段,旁边还专门写了注释:

/* 未知键原样保留:别人加的字段不该在保存时消失 */
/* 此处省略中间实现 */
if (KEYS.indexOf(k) < 0) out.unknown.push({ key: k, value: data[k] });

读的时候把多出来的键收集进 unknown 数组,意图是保存时或者下次合并时能把它们写回去。但全文搜一遍,serialize 只遍历 KEYS 那 14 项:

function serialize(values) {
  var out = {};
  KEYS.forEach(function (k) {
    out[k] = values && values[k] !== undefined ? values[k] : defaults()[k];
  });
  return JSON.stringify(out, null, 2);
}

unknown 数组从这里到那里没有任何一个读者。结果就是:读一份带了额外字段的配置文件,界面上一切正常;一保存,那些字段就没了。注释里写「不该在保存时消失」,代码里就是在保存时消失。

这类缺陷比逻辑反转更难发现,因为它没有报错、没有异常,功能看起来完全正常。只有真正拿一份外部配置文件走一遍导入导出才能看到——而自测时用的配置文件都是 default 序列化出来的,里面本来就没有未知键。

修法的选择取决于产品意图。如果确定不需要兼容外部键,那应当把注释和 unknown 数组一起删掉,别再让人误以为有这层保护。如果要保留,就把 unknown 交给渲染层的 S 对象存着,serialize 时拼在 14 个键后面。两条都能接受,不能接受的是现在这种「注释说有、代码里没有」。

第三条:报告里的时间戳有两个。

生成报告的路径上有两次取时间。buildCtx 里一次:

function buildCtx() {
  var tab = activeTab();
  return {
    stamp: U.stamp(new Date()),
    /* 此处省略其余字段 */
  };
}

makeReport 里一次:

function makeReport(quiet) {
  /* 此处省略其余实现 */
  S.reportText = RP.build(S.format, buildCtx());
  S.reportStamp = U.stamp(new Date());
  /* 此处省略其余实现 */
}

报告正文里的时间戳来自第一次,面板上「生成时刻」那一格显示的是第二次。两次取时间之间隔着一次完整的报告组装——一次 Markdown 拼接、可能的 CSV 转义、几十条事实条目的遍历。通常在同毫秒内完成,看不出差别;但当设备卡顿、报告条目多、或者正好跨在秒边界上时,两处的秒数就会差一。

这是一个典型的「同一事实算了两遍」问题。报告里写着 14:22:07,面板上写着 14:22:08,用户截图去提问题,开发看着两个不同的数没法解释。

修法很直接:先取一次时间,把结果存成局部变量,buildCtx 与 S.reportStamp 都用它。

var stamp = U.stamp(new Date());
S.reportText = RP.build(S.format, buildCtx(stamp));
S.reportStamp = stamp;

这类问题在别的工程里也很常见——状态条一个时间、日志一个时间、导出文件再一个时间。判断标准很简单:同一件事如果会在两个地方显示,就必须从同一个变量取值。

4.3 样式表的四条禁项

thorium.css 一共 751 行。文件开头两行注释先把禁项立好:进度与风险全部用文字与卡片呈现,不用进度条、不用动画、不用固定定位的悬浮层。

逐个特征值数下来,这几条禁项确实守住了:

特征出现次数说明
transition0只在文件头注释里提到
animation 与 keyframes0同上
position 取 fixed0全部定位靠常规流
will-change0未使用任何渲染层提示
感叹号加 important0没有强覆盖
@media 查询2两处宽度断点
自定义属性 var126统一主题变量
:root 声明2深浅两套变量
grid-template8表格型布局

零动画、零过渡、零固定定位、零强覆盖,这四条对一个要在鸿蒙 PC 上长期驻留的桌面应用来说不是保守,是必要的。动画在小屏幕上带来的是流畅感,在大屏幕上带来的是持续的合成层开销;一个停留在后台的窗口如果每秒都在跑动画,任务管理器里看得见。

两处媒体查询是仅有的响应式调整。126 处自定义属性把所有颜色、间距、字号全部收敛到两组变量里,深浅主题切换只需要改一处 :root。8 处 grid-template 用的是网格布局而不是浮动或绝对定位,这也解释了为什么整个样式表里没有一处 margin 负值与清除浮动的 hack。

深浅主题的实现方式值得一提:切换主题时改的是根节点上的 class,CSS 变量随之切换,所有部件跟着变,没有一行 JS 去逐元素改颜色。这跟渲染层「不碰元素 style」的铁律是同一件事的两面。

4.4 上架前必须替换的内容

前面几章里散落的替换项集中在这里:

项当前位置改成
包名com.huawei.ohos_electron申请到的正式包名
应用显示名ElectronThorium Browser
厂商example实际的开发者主体
签名材料本机三个绝对路径与两个加密码自己的签名证书与口令
目标版本未声明targetSdkVersion 显式写为 20
版本号1000000 与 1.0.0按提审节奏递增

签名材料那一项最容易被漏掉。build-profile.json5 的 signingConfigs 里写着三个绝对路径,开头都是本机用户名目录下的 .ohos/config,另有两个十六进制串形式的加密口令。这份文件一旦进公开仓库,等于把本机的签名配置连带口令一起交了出去。导出别处的工程后,第一件事就该是把这段替换成自己的——即便只是改别人的路径,也不能直接拿来用。

目标版本那一项不会报错,只会告警。四条告警静静躺在构建日志里,不影响出包,但意味着这个包的兼容目标不是主动声明的,而是跟 SDK 默认值走的。SDK 升级之后,同一个工程重新构建出来的包,运行时行为可能已经变了,而工程配置里一个字都没改。这种沉默的漂移最难追。

还有一类东西既不算替换也不算缺陷,但上架前要看一眼:构建日志里 ArkTS 编译告警一共 1363 行,集中在 web_engine 的适配层,量最大的几个文件是蓝牙低功耗适配、权限管理适配、窗口适配、蓝牙适配、状态栏管理、证书管理。这些是移植自上游的基础能力适配代码,不参与本应用的业务流程,但告警会跟着构建一起进日志。审核方如果抽查构建产物或日志,这些告警会被看到。上架前把 web_engine 里实际用不到的模块与告警一起清一遍,比在评审时解释它们是什么要容易得多。

五、构建与部署

图 1 地址栏输入 https://start.thorium.local/ 后的浏览器面板:徽章标注 HTTPS,解析结果分为协议、主机、端口、路径、查询、来源、风险计数、缩放八格,下方风险提示区与页面预览同步刷新

图 2 下载面板:新建任务区提供地址、文件名与四档限速,任务列表三个已完成条目均为 100%,下方统计七格把任务总数、进行中、失败、累计进度、已下载总量与限速并列展示

图 3 关于对话框:开源声明、免责声明与许可证三段内容,明确写出不含 Chromium 内核、不发起任何网络请求、不包含上游源代码

5.1 产物与构建日志

构建产物落在 electron 模块的 outputs 目录下,一次 release 构建得出四个文件:

文件字节数说明
electron-default-signed.hap195381097签名包,可安装
electron-default-unsigned.hap193921377未签名包
pack.info752打包元信息
mapping/sourceMaps.map572033源码映射,不进包

签名包与未签名包相差 1459720 字节,这一部分就是签名段与签名后重新对齐带来的开销。对一个接近两百兆的包来说,1.46 兆的签名开销占 0.75%,完全在预料之中。

sourceMaps.map 一共 572033 字节,比整个应用目录(189078 字节)还大两倍多。它记的是 ArkTS 编译产物的源码位置映射,供崩溃堆栈还原用。这个文件必须从提交物里排除——它包含完整的源码结构与变量名,对逆向分析者来说是一份现成的地图。目录里它是单独放在 mapping 子目录下的,这一点做得很规矩,不像有些工程会把它混在输出根目录里一起交付。

build.log 一共 663076 字节、7648 行。日志里能数出四次完整的构建,耗时分别是 3 秒 841 毫秒、4 秒 248 毫秒、4 秒 212 毫秒与 19 秒 945 毫秒,全部为成功,没有任何一次构建失败。前三次是增量构建,不到五秒就完;最后一次接近二十秒,才是包含了依赖收集与资源重编译的完整构建。这三个数字放在一起能看出一个重要结论:日常改业务代码的验证成本很低,五秒内就能看到结果;高频次、小步验证是完全可行的。

告警分四类:ArkTS 编译告警 1363 行、目标版本未声明告警 4 行、资源缺少基础副本告警 4 行,以及若干行调试级别的依赖加载信息。默认的目标版本与兼容版本已经在 2.1 节里对过了,最后包里的 apiVersion 写的是兼容 17、目标 20。

日志尾部还有一行 worker 退出码为 1 的记录。这是增量构建守护进程收尾时的正常输出,不是构建失败——同一份日志里最后一次构建结论是 BUILD SUCCESSFUL。看日志时只认这一行结论,比逐条去猜哪些是错误要快得多。

5.2 包的体积里到底是什么

一个一百八十六兆的包,业务代码占多少?先看整体:

项字节数占包比例
libelectron.so16747191285.72%
libadapter.so26212001.34%
libffmpeg.so21815281.12%
libc++_shared.so18256240.93%
四个原生库合计17410026489.11%
其余(ArkTS 产物、资源、签名段)2128083310.89%

libelectron.so 一个文件就占了 85.72%,因为 Electron 的运行时本身就是一整个 Chromium 加 Node 的静态链接产物。四个原生库加起来占 89.11%,剩下十多个兆里装着 ArkTS 编译产物、资源目录、hvigor 打包产生的中间物与签名段。

而本应用全部业务代码只有 189078 字节——占整包的 0.097%。九个引擎、一份渲染层、一份主进程、一套样式表,加起来不到两百 KB。这个比例解释了很多设计选择:为什么引擎可以写得那么细,为什么报告可以支持四种格式,因为这两百 KB 在整个包里的体积意义接近于零,多写一点逻辑不会带来任何体积代价。反过来说,想靠精简业务代码来给包减肥是不可能的——真正决定体积的是那个 167 兆的运行时。

剥离前后的对比值得单独看:

库未剥离字节数剥离后字节数比值
libelectron.so11436684401674719126.83
libadapter.so1549401626212005.91

两个库合计去掉 989069344 字节,接近九百四十三兆的调试符号。这也是为什么工程里要保留 lib.unstripped 目录——它是出问题时的唯一线索来源,而真正进包的是剥离后的产物。有一点容易搞错:libc++_shared.so 在两个目录里都在,但大小不一样,未剥离的那份反而是 1334688,比进包的那份小。这不是剥离出错,而是不同构建路径的产物本来就不一样,不能拿这两个数去算剥离比。

5.3 权限与设备形态

权限申报集中在 web_engine 模块的清单里,28 条权限项对应着 11 条 reason 说明与 11 条使用场景。也就是说有 17 条权限项只写了权限名,没写申报理由。

这是 Electron 系壳应用的普遍现象:web_engine 是共享库,里面装的是上游 Electron 与适配层的完整能力集,包括蓝牙、位置、相机、通讯录、存储、网络状态等等。这套能力集是通用的,不会因为宿主应用只用到了地址解析和本地文件读写就自动缩减。而本应用实际用到的只有本地文件读写与剪贴板两项。

上架时这一块的处理有两种思路。一种是逐条给 28 项权限补齐 reason 与使用场景——工作量不小,而且写了理由反而会引来「你为什么需要相机权限」的追问。另一种是从 web_engine 的清单里把确实用不到的能力项删掉,让包的权限面真正等于应用的能力面。对一个离线工作台来说,第二种才是对的:不去解释用不到的能力,而是让它不存在。

设备形态申报的是 2in1 与 tablet 两种。这个组合对一个需要键盘与较大窗口面积的浏览工作台是合适的:手机上装不了,平板上能用鼠标也能用触控,二合一设备上能当普通桌面软件用。如果只想上桌面,把 tablet 去掉会更干净;如果想覆盖更多设备,则需认真考虑更窄屏幕下那些三列网格布局应该怎么重排。

能力申报一共五个:三个 ability 与两个 extensionAbility。对纯离线工作台来说,EntryAbility 是唯一真正用到的;BrowserAbility、StatelessAbility、StatusBarEntryAbility、BrowserEmbeddedAbility 四个在业务上都没有调用点。它们会在安装时被注册,在扫描时被列出。上架须知里如果把版本亮点写成「内置浏览器」,这四个名字就会成为审核追问的切入点。把它写成一个用来练习浏览工作流的离线工具,与代码实际行为完全一致,也就没有追问的空间了。

六、常见问题与解决方案

Q1 暂停的任务点「继续」完全没有反应,只弹一句已经在队列中,是怎么回事?

问题现象:下载面板建一个任务,等它跑一会儿点暂停,状态变成暂停;再点继续,界面没有任何推进,状态条上弹出一句「任务已经在队列中,无需继续」。反复点多少次都一样,只有取消重建才能重新开始。

根因分析:这是 br-downloads 里 resume 函数的分支写反了。它先把暂停中的任务改成 queued,然后重新取出来判断状态,用「如果是 queued 就报错」的写法去校验。任务刚被自己改成 queued,于是这个条件必然命中,函数永远返回错误。同一个文件里的 retry 与 cancel 用的是反向写法——「如果不是目标状态就报错」,所以都是对的。只有 resume 一家把前置条件当成了后置条件,函数末尾那行无错返回成了永远跑不到的死代码。

解决方案:两处改动任选其一。直接把最后一行改成与 retry 一致的否定式,任务状态不是 queued 就报错,是就返回成功。或者更彻底一点,在 map 里把改动前的状态先存进一个字段,后面的判断全部基于旧状态,不再依赖「先改后判」这个顺序。改完之后建议把四个动作函数并排放一遍,确认它们使用的是同一种模式——导致这个 bug 的不是逻辑本身难,而是同一文件里两种相反的写法混着用。

教训:一个函数内部如果存在「先变更、再校验」两类语句,就要警惕校验条件写的是变更前还是变更后。更稳妥的做法是让校验函数不接收变更后的对象,而是接收变更前的快照。此外,渲染层拿到错误后直接返回本身也会掩盖问题——如果它能区分「状态冲突」与「参数非法」两类错误,这类问题在上手试用阶段就会被发现。

Q2 地址栏输入内网 IP,为什么没被识别为本地地址?

问题现象:在地址栏输入 192.168.1.1 或 10.0.0.1,解析结果里主机、端口、路径全部正确,但渲染出来的标记只有一条「直接使用 IP 访问,无法核对证书归属」,本地访问的那层识别完全没出现。历史样本里那条 127.0.0.1 的记录同样如此。

根因分析:br-url 里确实写了判断本地与内网的 isLocalHost,把 localhost、点 local 结尾、127 段、10 段、192.168 段与 172.16 到 172.31 段都分了进去,但它定义并导出之后没有任何一处调用。parse 里真正生效的是另一段内联正则,只认 localhost 与点 local 结尾两个条件,而且这段内联判断挂在 validIpv4 分支的后面——一个 IPv4 地址早在上一支就命中并返回了,根本走不到这里。于是 isLocalHost 里那四组地址段判断永远没机会执行,isLocal 对任何 IP 地址恒为假。

解决方案:让 parse 直接复用已导出的 isLocalHost,并把调用位置提到 IP 判定的前面,先判断是否本地再判断是否 IP,两件事不互斥。同时把那段内联正则删掉,同一个判定只留一份实现。如果希望「内网 IP」与「公网 IP」在风险级别上区分开,还需要调整那两条 warn 的文案,让本地访问不报证书风险。

教训:一个函数写好了但没被调用,比写错了还难发现——写错会有行为异常,没被调用则一切看起来正常,只是少了一部分能力。重构时把这类函数找出来的办法很简单:逐个导出项反向搜调用点,零调用的要么补上调用,要么删掉。两条都不会留下一个看起来对实际不生效的中间层。

Q3 导入别家浏览器导出的书签,文件夹怎么全串到最后一个去了?

问题现象:自建的书签导出再导入回来一切正常,文件夹归属分毫不差。但拿一份从别处导出的多层收藏夹文件导入,前面几层的书签全部被归到了最后一层文件夹名下,原文件里的目录结构在界面上看不出来了。

根因分析:fromHtml 逐行扫描时,遇到三级标题就把当前文件夹名记下来,遇到链接就用这个值当归属。问题是它只记了一个变量,没有栈——收藏夹列表是可以嵌套的,内层列表闭合之后,后面的链接本该回到外层文件夹,但没有层级信息可回退,folder 就一直停在内层最后那个标题上。导出侧是平铺的单层结构,所以自造样本走一遍看不出来。

解决方案:把单个变量换成数组当栈。遇到三级标题入栈,遇到列表闭合出栈,链接的归属取栈顶。没有标题时的默认文件夹保持不变。改完后拿三份不同浏览器导出的文件对比一遍,重点看嵌套两层的目录能否还回来。

教训:处理层级格式时,一层单一变量几乎总是不够的,必须用栈。同样的规律也适用于任何「逐行解析带嵌套标记」的场景——只要格式里存在配对的开闭标记,就用栈。另外自造样本永远只会覆盖自己写的那一种情况,格式兼容性的验证必须拿真实外部文件做。

Q4 报告正文里的时间与面板上的生成时刻差一秒,该信哪个?

问题现象:生成一份 Markdown 报告,报告头里写着某个时刻,同一屏上报告状态网格里「生成时刻」那一格写着另一个时刻,两处相差一秒。设备比较卡的时候差异更稳定,轻负载时偶尔对得上。

根因分析:生成路径上取了两次时间。buildCtx 组装上下文时先取一次用于报告正文,makeReport 在报告组装完成之后又取一次用于面板显示。两次之间隔着一整轮报告拼接,一旦跨过秒边界,两个数就不一样了。

解决方案:在最外层只取一次时间,存成局部变量,上下文与面板都传递这个变量,buildCtx 不再自己取时间。更彻底一点,把时间当成显式参数传给 buildCtx,让函数不再依赖当前时刻——这样报告引擎就变成了完全确定性的函数,同样的上下文在任何时候跑都出同样的文本,也才好写单元测试。

教训:同一事实如果在两个地方显示,就必须从同一个变量取值,不能各自去取。这类问题的特征很明显:不会报错、不抛异常、大部分时候看不出异常,但在时间边界上就会不一致,而且截图出去很难解释。审查时把同一屏上所有时间、总数、百分比列一遍,看看有没有两个地方各自算的。

Q5 构建日志里一千多条 ArkTS 告警,为什么包还能正常出来?

问题现象:打开构建日志,从下往上翻,满屏都是 ArkTS 告警,数下去超过一千三百条。但构建结论写的是成功,产物也正常生成、正常安装。这让人很难判断到底要紧不要紧。

根因分析:告警与错误是两个级别。告警表示编译器认为某段代码有隐患,但不阻止生成产物;错误才阻止。这些告警几乎全部来自 web_engine 的适配层,也就是移植过来的蓝牙、权限、窗口、状态栏、证书那一批基础能力适配代码,它们在本应用里并不参与业务流程,但依然要过一遍编译。日志里唯一能判定构建结果的,是那行写明了耗时的构建成功结论,以及包是否生成。

解决方案:看日志先看结论行,不要从第一条告警开始逐条阅读。确认产物已经出来之后,再把告警当作独立的优化任务处理:先按文件分组,看量最大的几个文件是不是根本用不到;如果用不到,直接不编译它们,告警自然消失;如果必须保留,再逐条去看属于哪一类。

教训:把告警当错误会让人麻木,麻木之后真正的错误也会被漏掉。一个工程如果常年挂着上千条告警,等于关掉了这门监控。上架前把它清到一个能逐条看完的数量,比事后去解释它们是什么要主动得多。

Q6 二十多条权限里为什么有一多半没写申报理由?

问题现象:打开共享库模块的清单,权限项一行一行往下,总数二十八条,但 reason 与使用场景只数到十一条,两边对不上。上架时审核会逐条核对权限与理由。

根因分析:web_engine 是从上游移植来的共享库,它的清单里写的是整套基础能力的权限集——蓝牙、位置、相机、通讯录、网络状态一一俱全。这套能力集是通用的,宿主应用只用到了其中两项,清单不会自动瘦身。reason 与使用场景是宿主应用申报时才需要填的,上游并没有为每个宿主填好。

解决方案:两条路。要么逐条补齐——但要先想清楚,给一个离线工具写「为什么需要蓝牙」的理由,本身就是一个很难回答的问题。要么从清单里删掉确实用不到的项,让包的权限面等于应用的能力面。对纯离线应用来说后一条是对的路:不去解释用不到的能力,而是让它不存在。

教训:权限清单应该当成功能清单来维护,而不是当成模板来填。每加一个能力就加一条权限,每删一个能力就删一条权限,两边始终对齐。拿别人的壳工程改东西时,第一个该看的就是清单——它告诉你这个壳以为自己是干什么的,往往与你打算让它干的事不是一回事。

Q7 为什么界面里连一个轻量的在线检查都做不了?

问题现象:想在设置面板里加一个「检查最新版本」的按钮,或者给环境面板加一个本地端口可达性检测,代码写下去根本没反应。控制台没有报错,网络请求也看不到,就是没反应。

根因分析:页面上的内容安全策略里,连接源被显式设成 none。这意味着 fetch、XMLHttpRequest、WebSocket、事件流与信标一律被拦,在发出去之前就被拦在渲染引擎里。连 127.0.0.1 都不例外——这个指令只管协议与源,不区分内外网。这不是 bug,而是这个应用刻意立下的约束:不联网这件事由策略强制,而不是靠代码自觉。

解决方案:接受这个约束,把「在线检查」这类需求改成本地检查。需要判断版本时,判断随包发布的版本号常量;需要判断可达性时,判断本地文件是否存在。如果确实需要一次真实网络请求,必须在 index.html 里放开该指令并同步修改环境面板上那一格的文案——两处必须同时改,否则面板上会写着「禁止」而实际已经发生。

教训:一条强约束最好写在一个能被检索到的地方,而不是写在十几个位置的注释里。这个工程的做法值得学:约束写在页面头部的策略里,结论写在环境面板上,中间没有第三处需要同步。另外要注意,加上这条策略之后,连开发者工具里排查网络问题的常规手段都会失效,因为根本没有请求发生——碰到「不生效但也不报错」的现象时,先看一眼策略,再去查代码。

七、总结

这套应用的结构可以一句话概括:九个纯函数引擎负责算,一个渲染层负责摆,一个主进程负责守。把完整的结构摊开来看:

层文件行数职责
壳边界main.js380窗口、路径纪律、九个 IPC
界面index.html411八个面板、九指令策略
样式thorium.css751126 个变量、零动画
渲染renderer.js1578DOM 组装、状态分发、文件读写
引擎九个文件2190解析、栈、集合、台账、报告
合计十四个文件5329189078 字节

从这套代码里能抽出三条经验。

第一,把能力边界做成数据,而不是做成文案。主进程返回的 unsupported 四条,被渲染层拿去做环境面板的格子内容与浏览器面板的提示语。好处不是省事,而是不会说谎——能力真的变了,只需改那四条,所有引用了它的地方自动跟着变;而如果每处都手写一句「本应用不联网」,总有一处会被遗忘,然后成为误导。一个应用说自己不做什么,这句话应当只有一个出处。

第二,确定性比真实感更值钱。下载面板没有任何真实传输,但它的每一个数字都能从输入推回去:速率由地址算哈希得到,总量由地址算哈希加上最小值,文件字节由速率乘时间累积。对同一份输入,任何人任何时候跑都得到同一张截图。这样做的意义在于可审查:评审方看到重复的数值不会当成 bug,反而能确认它不是随机。反之,如果速率是每次随机,那么无论功能做得多完整,都会被一句「这是假数据」挡回去。

第三,同一事实只能有一个出处。报告内的时间戳、面板上的时间戳、四格式报告里的同一个计数、浏览器面板与历史面板里的同一条地址解析结果,全部应该追溯到同一个计算点。4.2 节那条时间戳差一秒的缺陷,以及 3.4 节那张历史表导入后 id 错位的问题,都是同一个毛病的不同形态。这个毛病很少引发崩溃,但每一次都会在评审、截图、交付的时候消耗大量的解释成本。

上架前还有四件事必须做完。把模板包名、显示名与厂商三处一起换成正式信息,并在换完后重新装一遍确认桌面图标上的字已经变了。把 signingConfigs 里那份本机绝对路径与加密口令换成自己的签名材料,并确认这份配置文件不会进公开仓库。把 targetSdkVersion 显式写成 20,把四条目标版本告警清掉,别再跟 SDK 默认值走。把 web_engine 清单里用不到的权限与模块删一遍,让查询得到的权限条数真正等于应用实际需要的条数。

做完这四件,这套工程就从一个可运行的演示,变成了一个可以交出去的软件。它不会真的上什么网,但它的每一次地址解析、每一步前进后退、每一个下载任务的字节累积,都是可复现、可追溯、可解释的。在一个信息都在往云上飘的时代,一个把边界画得这么清楚的桌面工具,本身就有它的价值。

Logo

开源鸿蒙跨平台开发社区汇聚开发者与厂商,共建“一次开发,多端部署”的开源生态,致力于降低跨端开发门槛,推动万物智联创新。

更多推荐