本文记录 Sunshine 串流控制台在鸿蒙 PC 上的适配过程。这个应用面向的是 Sunshine 这款开源游戏串流主机的日常配置工作:把手写的 sunshine.conf 读进来、按已知键表收敛成带类型的值、校验互相冲突的组合、再原样写回去;把 apps.json 里的应用条目拆分命令、校验字段、按稳定顺序序列化;按显卡名与平台给出编码器推荐、被忽略的参数、码率建议与延迟估算;登记配对客户端台账;最后把主机配置、应用、客户端、编码结果与一轮本地演练汇总成一份可导出的报告。主进程不持有一份配置对象、不监听任何端口,也不做真实的 TLS 握手。文章按源码顺序拆解这条链路:主进程如何用八个通道把授权、读写与系统交互管住,七个纯函数引擎如何按依赖拓扑接到渲染层,配置的「载入不改直接保存」为什么能保持往返稳定,命令拆分为什么不能用空格切,确定性遥测如何用种子派生出一整条可复现的曲线,以及四种报告格式为什么必须读同一份上下文。文末给出逐条核出的十处工程缺陷与上架前必须做的替换项。

所有代码引用均来自仓库内 web_engine 模块下 resources/app 目录的真实文件,工程配置取自当前 ohos_hap 目录的实际状态。文中不出现虚构的性能数字与真机结论;凡是涉及耗时的表述,都以工程内可查的常量与源码路径为准,编码延迟与码率建议在界面上被明确标注为估算值。构建产物的字节数来自 electron/build/default/outputs 下实际存在的两个 hap 文件,体积构成按 libs/arm64-v8a 目录内四个 so 的真实大小换算。三张运行截图取自该构建在鸿蒙 PC 桌面环境下的实际界面。

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

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

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

一、技术架构分析

1.1 主进程只做四件事

main.js 的文件夹头把边界写得很直白:

/* Sunshine 串流控制台 —— 主进程

 * 只做四件事:开窗口、管路径授权(对话框是唯一入口)、把配置 / 清单 / 报告落盘、
 * 把系统剪贴板与文件定位接给渲染层。
 *
 * 配置文本的解析、应用清单的字段收敛、编码器评估、配对台账与会话仿真全在渲染层的
 * 纯函数引擎里跑:主进程不持有配置对象,也不监听端口。本壳不实现真实的串流协议,
 * 能力边界写在 app:info 的 unsupported 里,界面与报告照抄一遍。
 */

这四件事对应八个 IPC 通道,注释里编了号,从 1 到 8,连续没有跳号。八个通道按职责分三组:环境与元数据(1 app:info)、文件进出(2 conf:open、3 conf:save、4 apps:open、5 apps:save、6 report:save)、系统交互(7 clip:write、8 shell:reveal)。

比起同批其他壳应用,这里最值得注意的是「没有的东西」:没有端口监听通道、没有硬件枚举通道、没有进程启动通道。真实 Sunshine 干活的那三块——监听 47984/47989/47990/48010、探测显卡与驱动、拉起游戏进程——在这份主进程里一行都没有。取而代之的是 app:info 里的四条 unsupported:

unsupported: [
  '不实现 Moonlight 串流协议:不监听 47984 / 47989 / 47990 / 48010 端口,也不做 TLS 握手',
  '不采集真实显卡与驱动信息:编码器按名称与平台判断兼容性,不枚举设备',
  '不启动或接管真实游戏进程:应用清单只做配置、命令校验与序列化',
  '会话遥测是确定性仿真,用于比较参数,不代表真机延迟与帧率实测'
]

这四条不是文案装饰。它们与常量区是一套的:MAX_APPS 是 64、MAX_CLIENTS 是 16、MAX_CONF_BYTES 是 512 KB、MAX_REPORT_BYTES 是 8 MB,配置后缀固定为 conf、清单后缀固定为 json。界面上「环境与限制」面板读的正是这份数组与这些上限,没有任何第二处副本。

1.2 渲染层一条铁律

renderer.js 的开头同样把纪律写死:

/* Sunshine 串流控制台 —— 渲染层

 * 一条铁律:面板、报告、校验读同一份引擎结果。配置值来自 sn-config 的解析与收敛,
 * 应用清单来自 sn-apps,编码器评估来自 sn-encoder,配对台账来自 sn-pair,
 * 会话规划与遥测来自 sn-session,报告由 sn-report 组装;渲染层只做三件事:
 * 把值摆进面板、把曲线画到 Canvas、把路径类操作交给主进程。
 *
 * 平台约束:不弹系统对话框、不用原生下拉框、不拼 HTML 字符串(文本一律 textContent)、
 * 不碰元素 style、不用帧回调;会话推进只有 setInterval 一秒一步。
 */

这条铁律在这个应用里比在别处更容易被破坏,因为同一个数字在四个地方出现:主机配置面板的输入框里、视频与编码面板的兼容性摘要里、会话监控的图上、报告表格里。只要有一处自己另算,用户就会看到「面板说 92 分、报告说 88 分」。

工程的做法是把格式化也收进唯一出口。sn-util 里三个函数包办了界面上所有量纲:

function fmt(v, digits) {
  var n = Number(v);
  if (!isFinite(n)) return '—';
  var d = digits === undefined ? 3 : digits;
  if (Math.abs(n) >= 1000) return String(Math.round(n));
  return String(round(n, d));
}

function kbps(v) {
  var n = Number(v);
  if (!isFinite(n) || n < 0) return '—';
  if (n >= 1000) return round(n / 1000, 1) + ' Mbps';
  return Math.round(n) + ' kbps';
}

注意 fmt 那个一千的坎:绝对值大于等于 1000 时直接取整不带小数。这不是随手写的——码率、帧率、延迟混排在同一列时,12500 显示成 12500 比 12500.000 可读,而 26.5 又必须保留一位小数。分位数同理,sn-util 的 pctl 明确采用「升序后取不超过下标的最大值」而不是线性插值,理由是插值结果依赖于采样点分布,同一份数据换个实现就差一点,报告对不上账。

1.3 七个引擎的职责边界

七个引擎全部是 UMD 包裹的纯函数模块,加载顺序在 index.html 末尾固定:

<script src="engines/sn-util.js"></script>
<script src="engines/sn-config.js"></script>
<script src="engines/sn-encoder.js"></script>
<script src="engines/sn-apps.js"></script>
<script src="engines/sn-pair.js"></script>
<script src="engines/sn-session.js"></script>
<script src="engines/sn-report.js"></script>
<script src="renderer.js"></script>

这个顺序严格等于依赖的拓扑序:sn-util 无依赖;sn-config 只吃自己的键表;sn-encoder 被 sn-session 与 sn-report 间接依赖;sn-session 通过全局名字取 sn-encoder(文件里那行注释写着「引擎之间不互相 require:按名字取,Node 与浏览器里都能拿到同一份实现」);sn-report 最后加载,因为它要把前面所有引擎产出的结构体拼成一份上下文。

引擎行数字节职责
sn-util.js1774688数值收敛、格式化、FNV-1a 散列与线性同余发生器
sn-config.js54823282sunshine.conf 键表、解析、校验、预设与序列化
sn-encoder.js33512849四个编码器目录、兼容性判定、延迟与码率估算
sn-apps.js33812226apps.json 解析、命令拆分、校验与稳定序列化
sn-pair.js1907296配对码、证书指纹、客户端台账与在线状态
sn-session.js30312120会话规划、确定性遥测、汇总与建议
sn-report.js41517246四种格式的报告组装

七个文件合计 2306 行、89707 字节。整个 app 目录是 12 个文件、5651 行、209571 字节,引擎占字节数的 42.8%、行数的 40.8%,renderer.js 单独占 1721 行、63759 字节,两者加起来占全目录行数的七成、字节数的七成三,其余是 index.html 的 555 行、样式表的 702 行、main.js 的 355 行和一份 12 行的 package.json。

这个比例与同批的仿真类壳不太一样。那边的重心在引擎,这边的配置面板本身就有 40 个键要摆到界面上,渲染层不可能薄。也正因为如此,接口约定比行数更重要:每个引擎对外只暴露数据与判断,不碰 DOM、不碰 Node API、不读时钟——sn-report 的文件头专门写了「引擎里不取当前时间,时间戳由调用方传入,便于复现」。

二、环境准备

2.1 工程结构与 SDK 版本

工程沿用鸿蒙 Electron 壳的标准两模块布局。根 build-profile.json5 里与版本有关的部分是:

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

compatibleSdkVersion 是 5.0.5(17)、runtimeOS 是 HarmonyOS、collectAllLibs 打开——这一项必须为 true,否则打包时只搬运被显式引用的 so,electron 运行时里那些 dlopen 才加载的库会被漏掉,装到机器上就是启动即退出。与同批工程一样,products 里没有写 targetSdkVersion,而构建产物 pack.info 显示 target 20,说明这个值来自 SDK 侧默认而非本文件声明。

electron 模块的 module.json5 声明了三个 ability 与两个 extensionAbility:

名称类型进程exported说明
EntryAbilityability主进程truemainElement,带 entity.system.home 与 link scheme
BrowserAbilityability:browserfalse处理 viewData 的内部浏览容器
StatelessAbilityability:browsertrue无状态多窗口实例
StatusBarEntryAbilityextensionAbility——type 为 statusBarView
BrowserEmbeddedAbilityextensionAbility——type 为 embeddedUI

deviceTypes 是 [“2in1”, “tablet”],pack.info 里打包出来的 deviceType 数组与它完全一致,没有出现声明一套、产物另一套的情况。

还有一处值得单独记下来。根 build-profile.json5 的 signingConfigs 里,certpath、profile、storeFile 三个字段都是本机绝对路径(指向用户目录下的 .ohos/config),keyPassword 与 storePassword 是加密后的口令串。这份文件是能构建的必要条件,但它同时也是「开发机目录结构 + 签名材料位置」的完整说明书。仓库如果对外分发,这一节要么换成占位符、要么确认该文件在忽略列表里——第四章的替换项会再提一次。

2.2 依赖与构建配置

两个模块各自的 oh-package.json5 承担不同职责。electron 只是把 web_engine 拉进来:

{
  "license": "",
  "devDependencies": {},
  "author": "",
  "name": "electron",
  "description": "Please describe the basic information.",
  "main": "",
  "version": "1.0.0",
  "dependencies": {
    "web_engine": 'file:../web_engine',
  }
}

web_engine 才是真正带原生库的那一层:

{
  "name": "web_engine",
  "version": "1.0.0",
  "main": "Index.ets",
  "license": "Apache-2.0",
  "devDependencies": {
    'libadapter.so': 'file:./src/main/cpp/types/libadapter',
  },
  "dependencies": {
    "inversify": "^6.0.1",
    "reflect-metadata": "^0.1.13"
  }
}

inversify 与 reflect-metadata 是 web_engine 内部容器注入所需,与业务代码无关;libadapter.so 通过 file 协议指向 cpp 目录下的类型声明包,真正的二进制放在 electron/libs/arm64-v8a 下。electron 这一份的 license 是空字符串,web_engine 这一份是 Apache-2.0——这个差异在第四章会成为缺陷 D9 的一部分,因为它与界面上关于对话框里写的许可证不是同一个答案。

两份 build-profile.json5 都把 release 分支的混淆打开,且各有各的附加项:

{
  "name": "release",
  "arkOptions": {
    "obfuscation": {
      "ruleOptions": {
        "enable": true,
        "files": ["./obfuscation-rules.txt"]
      },
      "consumerFiles": ["./consumer-rules.txt"]
    }
  }
}

上面是 web_engine 那一份,多一个 consumerFiles 指向 consumer-rules.txt,这是 HAR 被依赖方继承混淆规则的入口。electron 那一份没有 consumerFiles,但 targets 里多一个 ohosTest 目标,供测试工程使用。两份文件都带尾逗号,JSON5 允许,把它当严格 JSON 解析的工具会报错。

整个 ohos_hap 目录里,六份 JSON5 配置合计有 10 处尾逗号:

文件尾逗号处数
electron/build-profile.json53
web_engine/build-profile.json51
electron/src/main/module.json53
web_engine/src/main/module.json51
electron/oh-package.json51
web_engine/oh-package.json51

工程里还有一份 docs 目录,五个文件合计 2086134 字节,全部是与业务无关的上游适配资料:electron-example.zip 2226 字节、electron-napi-library.zip 66845 字节、ets-adapter.zip 7432 字节、electron 调用 ets 指导文档 1388663 字节、鸿蒙平台 Electron 加载 addon 的说明 620968 字节。前三份是样例工程压缩包,后两份是指导文档。它们不参与构建,但会随仓库分发,提交前应当确认是否需要随包——三个 zip 加起来不到 80 KB,两份 PDF 占了将近 2 MB。

2.3 运行环境与能力自检

界面第七个面板「环境与限制」不是装饰。环境一栏列出应用版本、Electron、Node、Chromium、平台,然后是四个上限:应用上限 64、客户端上限 16、配置上限 512 KB、报告上限 8 MB。这些数字全部来自 app:info 那一次调用,缺失时渲染层有兜底常量,但正常情况下不会走到兜底分支。

能力边界那一栏由 sn-report 拼出来:

function limits(ctx) {
  var base = (ctx && ctx.unsupported) || [];
  return base.concat(EXTRA_LIMITS);
}

base 是主进程 app:info 里的那四条,EXTRA_LIMITS 是引擎侧自己补的四条,措辞不同但指的是同一件事。两份拼起来正好覆盖「不监听端口」「不读硬件」「不启动进程」「遥测是仿真」四个边界,报告末尾的「能力边界」小节读的也是这同一个函数。

同一个面板里还有「重新探测」按钮,点下去走 selfTest,把七项能力逐条点亮:

S.caps = [
  { name: '配置引擎', on: !!CFG, note: CFG ? '解析 / 校验 / 预设' : '未装载,配置面板不可用' },
  { name: '编码器引擎', on: !!ENC, note: ENC ? '目录 / 兼容性 / 码率' : '未装载,无法评估' },
  { name: '应用清单引擎', on: !!APPS, note: APPS ? '解析 / 校验 / 序列化' : '未装载,清单只读' },
  { name: '配对引擎', on: !!PAIR, note: PAIR ? 'PIN / 台账 / 指纹' : '未装载,不能登记设备' },
  { name: '会话引擎', on: !!SESS, note: SESS ? '规划 / 确定性遥测' : '未装载,不能演练' },
  { name: '报告引擎', on: !!RP, note: RP ? 'MD / JSON / CSV / TXT' : '未装载,不能导出' },
  { name: '画布 2D', on: canvasOk, note: canvasOk ? '曲线绘制可用' : '当前环境不支持 2D 画布' }
];

这套自检在鸿蒙 PC 上有明确意义:没有 DevTools 的机器上,如果某个引擎文件因为打包疏漏没进包,控制台之外不会有任何提示,用户看到的是「界面在、按钮点了没反应」。renderer.js 的第一个模块级语句就是在用 eng() 取引擎时加 try/catch,取不到就返回 null,所有渲染函数都以「引擎为空就换一个徽章文案」收尾,而不是直接崩。

三、核心适配流程

3.1 路径纪律与八个通道

主进程的路径纪律由六个函数组成,与同批其他壳应用结构一致:

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;
}

isInside 用「父路径加斜杠」做前缀判断而不是裸前缀:没有那个斜杠,/data/app 会把 /data/application 认成自己的子路径。win32 分支统一转小写也是必要的,同一条路径大小写不同却指向同一个文件时,字符串比较会给出两个答案。

真正调用 guard 的通道也只有一个:

handle('shell:reveal', function (req) {
  var file = fwd(req.path || '');
  guard(file);
  if (!fs.existsSync(file)) return { success: false, error: '路径不存在' };
  shell.showItemInFolder(file);
  return { success: true, path: file };
});

这是合理的:读配置走 conf:open、写配置走 saveText,路径都由系统对话框产生,两端都在产生路径的当下调用 rememberRoot 记录父目录;shell:reveal 吃的是渲染层传回来的上一次保存路径,属于外部可构造的输入,必须过 guard。

saveText 的四步顺序值得抄一遍:

async function saveText(req, opt) {
  var o = opt || {};
  var text = String((req && req.text) || '');
  if (!text.trim()) return { success: false, error: (o.what || '内容') + '为空,未写入文件' };
  var bytes = Buffer.byteLength(text, 'utf8');
  var cap = o.maxBytes || MAX_REPORT_BYTES;
  if (bytes > cap) {
    return { success: false, error: (o.what || '内容') + '超过 ' + sizeText(cap) + ' 上限' };
  }
  ...
  rememberRoot(path.dirname(file));
  fs.mkdirSync(path.dirname(file), { recursive: true });
  fs.writeFileSync(file, text, 'utf8');

空内容与超限都在弹对话框之前就拒掉,用户不会白填一次文件名。rememberRoot 放在 mkdirSync 之前,顺序不能反——先记授权再建目录,等于「先允许在这片地方写,再去确保这片地方存在」。

打开方向的 openText 多做了三件事:先 stat 再读、非文件拒绝、超过 512 KB 拒绝。这三个判断都在读文件之前,所以选错一个几百兆的镜像文件时,得到的是「超过 512 KB 上限」这类可读的拒绝,而不是把整个文件读进内存再崩掉。

八个通道的入参与出参统一成 { success, error, code } 三元组,失败时 error 一定是中文,main.js 里那张 ERR_TEXT 表有十二条,errText 再做一层兜底——异常消息里本身是中文就直接透传,否则折叠成「系统调用失败(错误码 X)」,绝不把英文系统原文和绝对路径漏到界面上。理由是导出截图与反馈截图会到处流传。

handle 那层包装处理了异步分支:

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);
    }
  });
}

其中三个通道是 async——conf:save、apps:save、report:save 内部都要 await 对话框——其余五个是同步。只写同步 try/catch 的话,await 之后抛出的异常会变成 rejected promise,渲染层收到的是原始错误对象而不是约定的三元组,界面上就会显示 undefined。

3.2 配置解析与往返稳定

sn-config.js 是这七个文件里最大的一个,548 行里绝大部分是键表。SCHEMA 一共 40 个键,按五个组归类:网络与端口、视频与编码、音频、输入、运行时与日志。每个键至少带四样东西——中文标签、所属组、类型、默认值,可选的还有上下界、枚举选项与帮助文案:

port: {
  label: '基础端口', group: 'network', type: 'int', dflt: 47989, min: 1029, max: 65000,
  help: 'HTTPS / Web UI / RTSP 端口都由它派生,改动时三处一起变'
},

这张表是唯一的真源:界面上的输入框回写、报告里的分组小标题、CSV 的分类列、校验报错时定位到哪个键,全部从 SCHEMA 读。界面上「配置项 40」这个数字就是 KEYS.length,不是硬编码的 40。

把一行文本收敛成带类型的值由 coerce 完成,三类各有各的拒绝理由:

if (s.type === 'bool') {
  var low = t.toLowerCase();
  if (BOOL_ON.indexOf(low) >= 0) return { value: 'on' };
  if (BOOL_OFF.indexOf(low) >= 0) return { value: 'off' };
  return { error: '只接受 on / off' };
}
if (s.type === 'int') {
  if (!/^[+-]?\d+$/.test(t)) return { error: '必须是整数' };
  var n = parseInt(t, 10);
  if (s.min !== undefined && n < s.min) return { error: '不能小于 ' + s.min };
  if (s.max !== undefined && n > s.max) return { error: '不能大于 ' + s.max };
  return { value: n };
}

布尔接受 on/true/yes/1/enabled 与 off/false/no/0/disabled 两组写法,但落盘时统一成 on 与 off;整数先过正则再过范围,避免 parseInt 把 12abc 读成 12。

parse 的返回值是个结构体而不是裸对象,这是往返稳定的关键:

return {
  values: values,
  extra: extraList,
  order: order,
  errors: errors,
  duplicates: duplicates,
  count: count
};

values 里放的是已知键,未知键不进 values 而是单独进 extra,注释与空行跳过,同一键出现多次时记进 duplicates 并给出「以最后一次为准」的提示。把未知键留下的理由很实际:Sunshine 上游随时会加新键,本壳不认识就丢掉的话,用户拿这份配置回去启动 Sunshine 会发现少了半页设置。

序列化方向同样按组顺序输出,未知键单独放末尾:

GROUPS.forEach(function (g) {
  var keys = KEYS.filter(function (k) { return SCHEMA[k].group === g.id; });
  out.push('# ---- ' + g.name + ' ----');
  keys.forEach(function (k) {
    var val = v[k] === undefined ? SCHEMA[k].dflt : v[k];
    var s = SCHEMA[k];
    if (val === '' && s.dflt === '') return;
    out.push(k + ' = ' + fmtValue(k, val));
  });
  out.push('');
});

三条规则合起来保证了「载入 → 不改 → 保存」的往返稳定:键的顺序由 GROUPS 与 KEYS 决定而不是由原文件的书写顺序决定;空字符串且默认值也是空字符串的键直接跳过,不会写出四十行 xxx =;未知键原样保留在末尾。反过来说,如果原文件键序与 GROUPS 不同,保存后的文件在文本上会变一次——这一点在 Q2 里专门说明。

端口派生是这份配置里最容易出错的一处。Sunshine 的 47989 只是基础端口,另外三个由它推出来:

function derivedPorts(base) {
  var p = Math.round(Number(base) || 47989);
  return {
    http: p,
    https: p - 5,
    webui: p + 1,
    rtsp: p + 21
  };
}

界面把四个端口摆成一行,报告里也一样,两边都调这一个函数。截图里的四行读数——HTTPS(配对)47984、HTTP 47989、Web UI 47990、RTSP(视频)48010——正是基础端口 47989 代入后的结果。校验里还有一条与之呼应:端口不在 1029 到 65000 之间就报错,理由是「否则派生出的 HTTPS / RTSP 端口会越界」,因为 HTTPS 要减 5,RTSP 要加 21。

预设做了三档,低延迟、均衡、画质优先,applyPreset 只改与预设相关的键:

Object.keys(p.values).forEach(function (k) {
  var before = out[k];
  var after = p.values[k];
  if (String(before) !== String(after)) changed.push({ key: k, from: before, to: after });
  out[k] = after;
});

返回的 changed 列表被界面拿去渲染「影响项」,所以用户点一下预设,看到的不是「已应用」三个字,而是「改了 9 项」加上具体是哪些键。这条设计避免了一个常见误解:预设听起来像是把整份配置重置,实际上端口、应用、配对都不受影响。

3.3 应用清单与命令拆分

apps.json 是顶层数组,每一项描述 Moonlight 里能看到的一个「应用」。sn-apps 负责把它收敛成内部结构,关键动作是字段双向兼容:

/* 同时接受 apps.json 的 kebab-case 与内部驼峰:编辑已有条目时不能把字段清掉 */
function pick(raw, kebab, camel) {
  return raw[kebab] === undefined ? raw[camel] : raw[kebab];
}

working-dir 与 workingDir、image-path 与 imagePath、auto-detach 与 autoDetach、wait-all 与 waitAll、exit-timeout 与 exitTimeout、prep-cmd 与 prep,六组字段都走这一个 pick。如果只认一种写法,用户从 Sunshine 上游复制来的清单在编辑之后会被悄悄清空一半字段——界面上看不出任何错误,保存出来的文件却少了几行。

命令拆分是这个文件里最讲究的一段。Sunshine 启动应用时不经过 shell,命令是按空格切成 argv 直接传给进程的,所以渲染层的预览必须与它的切法一致:

for (var i = 0; i < s.length; i++) {
  var ch = s.charAt(i);
  /* 引号内只把 \" 与 \\ 当作转义:Windows 路径里的反斜杠要原样留下 */
  if (ch === '\\' && quoted && i + 1 < s.length) {
    var nx = s.charAt(i + 1);
    if (nx === '"' || nx === '\\') {
      buf += nx;
      i += 1;
      continue;
    }
  }
  if (ch === '"') {
    quoted = !quoted;
    ...

这段状态机有一个容易忽略的细节:反斜杠只在引号内、且后面跟的是引号或反斜杠时才当转义。原因是 Windows 路径里反斜杠满地都是,如果无条件转义,C:\Games\Doom 会被解析成 C:GamesDoom。函数返回的不只是数组,还带一个 error 字段——引号没闭合时给出「命令里的双引号没有闭合」,界面上徽章直接变红。

校验函数返回的每一行都带 index,指回清单里的位置:

list.forEach(function (a, i) {
  var name = String((a && a.name) || '').trim();
  var cmd = String((a && a.cmd) || '').trim();
  if (!name) errors.push({ index: i, name: '', text: '第 ' + (i + 1) + ' 项没有名称' });
  ...

这样面板上能直接写「第 3 项没有名称」,而不是让用户自己在四十条里找。三个典型错误各有分工:名称重复是错误(Moonlight 里两个同名应用没法区分)、命令为空是提示(只串流桌面是合法用法)、工作目录写成相对路径是提示(会按配置文件所在目录解析,常常不是用户以为的位置)。

序列化方向刻意只写非默认字段:

out.name = String(a.name || '');
out.output = String(a.output || '');
out.cmd = String(a.cmd || '');
if (String(a.workingDir || '')) out['working-dir'] = String(a.workingDir);
if (a.excludeGlobalPrep) out['exclude-global-prep-cmd'] = true;
if (a.elevated) out.elevated = true;

name、output、cmd、exit-timeout 四项恒写,其余仅在与默认值不同时出现。这与配置文件的序列化是同一套思路,目的也一样:让保存出来的文件更像人手写的,同时保证同一份清单每次导出一致。

内置模板有三档:桌面(空命令)、Steam 大屏(steam -bigpicture)、RetroArch(带一组准备与撤销命令示例)。点模板只填草稿,不直接进清单——草稿区的「保存应用」才是落点,这个两步设计让它同时能用于新建和编辑。

这里埋着第四章的缺陷 D6:草稿回填时只读 prep 的第一组。

var prep = (d.prep && d.prep[0]) || { do: '', undo: '' };
setInput('txtPrepDo', prep.do);
setInput('txtPrepUndo', prep.undo);

界面上只有一对 do/undo 输入框,读回来时也只写回第一组,第二组之后的内容既看不见也改不了,但保存时它们仍在数组里。对一个只用手写 JSON 的用户没影响,对用界面编辑的用户就意味着「我明明删掉了准备命令,保存后它又回来了」。

3.4 编码器评估与延迟估算

编码器目录只有四条,每一条都写清了厂商、支持的平台与支持的编码格式:

id名称厂商平台编码格式
nvencNVIDIA NVENCnvidiawin32 / linuxh264、hevc、av1
amdvceAMD AMF / VCEamdwin32 / linuxh264、hevc、av1
vaapiVAAPIintellinuxh264、hevc、av1
software软件 x264cpuwin32 / linux / darwinh264

这四条不来自设备枚举,全部是常量。判断用不用得上,靠自己写显卡名的模式匹配:

function vendorOfAdapter(name) {
  var s = String(name || '').toLowerCase();
  if (!s) return '';
  if (/nvidia|geforce|quadro|tesla|\brtx\b|\bgtx\b/.test(s)) return 'nvidia';
  if (/amd|radeon|firepro|instinct|\brx\b/.test(s)) return 'amd';
  if (/intel|arc|iris|uhd|hd graphics/.test(s)) return 'intel';
  if (/apple|\bm1\b|\bm2\b|\bm3\b|\bm4\b/.test(s)) return 'apple';
  return '';
}

rtx、gtx、rx 三处都加了词边界——不加的话,任何包含这几个字母组合的名字都会被算进来,而显卡型号里这种巧合并不少。认不出厂商就返回空串,由推荐函数决定回落到软件编码,而不是猜一个。

真正协商的编码格式由两个模式键决定,规则是强制档位优先:

function codecFromModes(values) {
  var v = values || {};
  if (Number(v.av1_mode) >= 2) return 'av1';
  if (Number(v.hevc_mode) >= 2) return 'hevc';
  return 'h264';
}

两个模式都是「自动、关闭、允许、强制」四档,数值 2 是强制、3 也是强制。所以先判 av1 再判 hevc:两者都强制时 AV1 胜出,因为 AV1 的压缩效率更高,玩家既然强制了,说明设备支持。

推荐是一棵自上而下的决策树,每个分支都带一句人话理由:

if (vendor === 'nvidia') {
  pick = 'nvenc';
  reason = '检测到 NVIDIA 显卡,NVENC 延迟与画质最均衡';
} else if (vendor === 'amd') {
  pick = 'amdvce';
  reason = '检测到 AMD 显卡,AMF 在超低延迟档更合适';
} else if (vendor === 'intel') {
  if (platform.indexOf('linux') >= 0) {
    pick = 'vaapi';
    reason = 'Linux + Intel 显卡走 VAAPI,内核驱动即可用';
  } else {
    pick = 'software';
    reason = 'Windows 上没有 Intel 硬件编码路径,只能走软件编码';
  }
}

Intel 那一支是有意写得别扭的:Windows 上确实有 QSV 这条路,但这份配置键表里没有对应编码器条目,与其推荐一个不存在的 id,不如老实说只能走软件编码。决策树末尾还有两道回落——首选编码器与平台不匹配、或者不支持目标格式,都会退到 software 并把原因写进 alts 数组。

参数是被忽略还是生效,也是算出来的,不是文档里列的:

function appliedKeys(id) {
  var keys = ['encoder', 'qp', 'max_bitrate', 'hevc_mode', 'av1_mode'];
  return keys.concat(OWN_KEYS[id] || []);
}

五个公共键恒生效,再加上这个编码器自己的专属键。被忽略的一侧取补集,且只统计「被改过」的键——默认值留着的参数即便属于别的编码器,也不会占用提示栏。

编码器选自动时走的是另一条短路:

if (!id) {
  /* 留空是合法的「自动选择」:按兜底编码器评估,但把不确定性说清楚 */
  warnings.push('编码器为自动选择:以下评估按 H.264 + 软件编码兜底,选定编码器后结论更准');
  return { ok: true, errors: errors, warnings: warnings, applied: appliedKeys('software'), ignored: [] };
}

这条短路决定了首屏的样子:开箱状态没有选编码器,面板照样给出一整套评估结果,但顶上一句提示说明这是兜底口径。截图里的「7 项生效」就是这段的产物——appliedKeys(‘software’) 等于五个公共键加 sw_preset 与 sw_tune 两个专属键。

延迟估算拆成三段,每段都能在上面找到系数:

var base = { nvenc: 4.5, amdvce: 5.2, vaapi: 6.0, software: 14 }[id];
var encMs = Math.max(1.5, base + adj);
var netMs = 6 + Number(v.max_bitrate || 20000) / 1000 * 0.05;
var decodeMs = 3.5;

界面上那个 26.5 ms 正是三段相加:软件编码基准 14 ms,预设项不在映射表里按 0 计,未开启 zerolatency 再加 2,编码段 16.0 ms;网络段按码率上限 20000 算得 6 + 20000 / 1000 × 0.05 = 7.0 ms;解码段固定 3.5 ms。16.0 + 7.0 + 3.5 = 26.5。三段各自取一位小数后相加再四舍五入,不保留中间浮点尾数,界面上看到的每一位都能手工验算。

顺带一个容易被忽略的设计:网络段的输入用的是码率上限而不是实际码率。理由是串流卡顿取决于管道最窄处,用上限估更接近最坏情况;代价是上限设得越夸张,估算越悲观——这也是为什么后面码率那一栏不看估算值而看建议区间。

码率建议按每像素每帧比特数推:

var bpp = { h264: 0.085, hevc: 0.06, av1: 0.05 }[codec] || 0.085;
var rec = Math.round(w * h * f * bpp / 1000);
if (w * h >= 3840 * 2160) rec = Math.round(rec * 0.82);
rec = Math.max(2000, Math.min(200000, Math.round(rec / 500) * 500));

1920×1080、60 帧、H.264 代入:1920 × 1080 × 60 × 0.085 / 1000 = 10575,按 500 对齐到 10500,于是界面写「10.5 Mbps」。上下两档分别是 0.65 倍与 1.5 倍,再各自对齐——这就是 7000 与 16000 的来历,也正是截图里那条「码率上限 20000 kbps 高于本分辨率的建议上限 16000 kbps」的来源。对齐到 500 不是为了好看,是为了同一组参数在任何机器上算出来的数字完全一致。

最后的综合评分是一行减法:

var score = 100 - c.errors.length * 30 - c.ignored.length * 3 - warnings.length * 4;

错误一条扣 30,被忽略参数一条扣 3,警告一条扣 4,结果再夹到 0 到 100 之间。开箱状态没有任何错误、没有忽略参数、两条警告(自动选择兜底、码率上限超建议上限),100 − 2 × 4 = 92 分。这个分数在兼容性面板、报告表格和校验结果里是同一个值,因为三处都调同一个 evaluate。

3.5 配对台账与会话规划

配对码不是随机数,是种子派生出来的四位:

function makePin(seed) {
  var n = hash32('pin:' + String(seed == null ? 0 : seed)) % 10000;
  var s = String(n);
  while (s.length < 4) s = '0' + s;
  return s;
}

用 FNV-1a 散列再对一万取模,同样的种子永远得到同一个码。这样一个没有故障注入的配对流程才是可回归的:报告里记下种子,任何时候都能重放出同样的四位数字。证书指纹同理,取 uuid 与四个下标各自散列,拼成四组四位十六进制:

for (var i = 0; i < 4; i++) groups.push(hex4(hash32(u + ':' + i)));

这份指纹只用于界面辨识,不做任何加密验证——main.js 的 unsupported 第一条已经把「不做 TLS 握手」写死了。

登记一台设备要过九道前置校验,顺序是刻意排的:

if (!name) return { ok: false, clients: arr, error: '请填写客户端名称' };
if (name.length > 40) return { ok: false, clients: arr, error: '客户端名称不能超过 40 个字符' };
if (!uuid) return { ok: false, clients: arr, error: '请填写设备标识(UUID)' };
if (!uuidOk(uuid)) return { ok: false, clients: arr, error: '设备标识只允许 8–64 位十六进制与连字符' };
if (!expected) return { ok: false, clients: arr, error: '还没有生成配对码:先点「生成配对码」' };
if (info.expired) return { ok: false, clients: arr, error: '配对码已超过有效期,请重新生成' };
if (!/^\d{4}$/.test(pin)) return { ok: false, clients: arr, error: '配对码必须是 4 位数字' };
if (pin !== expected) return { ok: false, clients: arr, error: '配对码不正确' };
if (find(arr, uuid) >= 0) return { ok: false, clients: arr, error: '该设备已经配对,不能重复登记' };

名称与标识先校验,是因为这两项是用户能改的;过期先于比对,是因为一个过期的码即便填对了也不该放行;重复登记放在最后,是因为前八道都过不了时,那条「已经配对」的提示会误导用户以为自己只差一步。每一道失败都返回新的数组副本,原台账一个字节都不动。

在线状态是纯时间比较:

function statusOf(client, now) {
  var seen = Number(client && client.lastSeen) || 0;
  if (!seen) return { key: 'idle', label: '待连接' };
  if ((Number(now) || 0) - seen <= ONLINE_MS) return { key: 'on', label: '在线' };
  return { key: 'off', label: '离线' };
}

ONLINE_MS 是 120000,注释写着「两分钟内有心跳算在线:这个阈值与界面提示保持一致」。问题出在 lastSeen 由谁更新——引擎里有 touch 函数负责刷新,但全项目没有任何地方调它。这就成了第四章的 D2:打开示例台账看到两台设备都是「在线」,其实那是归一化时把固定时间戳写进去的结果,放上两分钟就全变离线,而且没有任何界面动作能让它们回来。

会话规划把问题分成两档,这一分档决定了按钮能不能点:

if (!app) errors.push('应用清单为空:先在「应用清单」里新建一个应用');
if (!cls.length) warnings.push('还没有配对客户端:会话只能做本地演练,不会真的有设备连进来');
var bitrate = Math.min(cap, guide.rec);

错误只有一条——清单为空,因为应用是会话的必要条件;客户端为空只是警告,因为本地演练本来就是允许的。这条划分与界面上的按钮禁用逻辑严格对应,报告里也照抄:错误进「阻塞项」,警告进「风险项」。

码率取上限与建议值的较小者,这一行同时解决了两个方向的错配:上限设得太低,实际就低;上限设得太高,也不会真的按那个数字发数据。面板上「上限封顶」那一行显示的就是这个 min 的结果。

分辨率四档、帧率四档,帧率不在候选里就回落到 60:

var fps = FPS_LIST.indexOf(Number(r.fps)) >= 0 ? Number(r.fps) : 60;

这样处理而不是夹取,是因为 45 帧这种值既不是客户端能协商的档位,也不该被悄悄改成 30 或 60——回落到默认值,行为可预期。

规划结果里那个 guide 字段有一处口径不一,记作 D4:

var guide = E ? E.bitrateGuide(res, fps, codec) : { low: 3000, rec: 12000, high: 20000 };

编码器引擎在场时走真实的每像素比特公式,不在场时用一组写死的常数。这组常数与 sn-encoder 在 1080p60 H.264 下的结果(7000 / 10500 / 16000)明显不是一套。因为七个引擎是一起打包加载的,实际运行时几乎走不到兜底分支,但它意味着「引擎缺失时界面给出的建议仍然看起来像模像样」,而这正是最危险的一种降级——用户不会知道自己在看一个假的区间。

3.6 会话遥测与四种报告

一步仿真的随机量全部从状态里的种子派生,没有任何一处调用 Math.random:

var seed = (Math.imul(s.seed >>> 0, 1664525) + 1013904223) >>> 0;
var tick = s.tick + 1;
var r1 = seed / 4294967296;
var r2 = ((seed * 69069 + 1) >>> 0) / 4294967296;
var r3 = ((seed ^ 0x9e3779b9) >>> 0) / 4294967296;

var spike = tick % 17 === 0;
var fps = s.baseFps - r1 * 2.2 - (spike ? 3.5 : 0);

seed 走一遍线性同余,再用乘 69069 与异或 0x9e3779b9 两种混合各派生一个独立的数。三种混合互相不相关,避免帧率、码率、延迟三条曲线同涨同落。尖峰每 17 步一次,写成取模而不是概率抽样,是因为概率抽样会让「第几步有尖峰」依赖采样历史,同一份报告隔天再跑就差一截。

延迟在尖峰步上直接加 12 到 20 ms,丢包从 0.45% 量级跳到 1.2% 到 2.6%。这些数字是仿真参数,不是实测——界面上「会话遥测是确定性仿真」那句话就写在 unsupported 第四条里。

每步都要算一次质量分:

if (latency > 30) lost += (latency - 30) * 1.2;
else if (latency > 20) lost += (latency - 20) * 0.5;
lost += deficit * 180;
lost += loss * 600;

延迟分两段加权:20 到 30 ms 之间每毫秒扣 0.5,超过 30 ms 每毫秒扣 1.2,越往后越陡。帧率缺口按比例乘 180,丢包率乘 600——按这个权重,1% 的丢包大致相当于 3.3 个百分点的帧率缺口,与串流玩家的直觉一致:丢包比掉帧更难受。分数落在 85 以上是优、70 以上是良、50 以上是一般,其余是差。

历史只留最近 120 条:

var history = s.history.concat([sample]);
if (history.length > HISTORY_MAX) history = history.slice(history.length - HISTORY_MAX);

一小时一秒一步正好三千六百步,全留会把渲染层拖死。裁到 120 条后,曲线图显示的是最近两分钟,而汇总指标算的也是这 120 条——这一点在界面上有标注,否则用户会以为平均数覆盖了整场会话。

汇总与建议读同一份历史:

function pctlOf(key, p2) {
  var arr = h.map(function (s) { return num(s[key], 0); }).sort(function (a, b) { return a - b; });
  var i = Math.min(arr.length - 1, Math.max(0, Math.ceil(p2 * arr.length) - 1));
  return arr[i];
}

p95 用的是取下标不插值,与 sn-util 的 pctl 是同一口径,报告里那一列因此可以被手算复核。

报告四种格式共用一份上下文,写入文件前先把会话冻结:

S.activePlan = S.plan;

冻结这一步很关键。会话在跑,规划却在跟着表单变——用户改一下分辨率,如果不冻结基准,报告里的目标分辨率与实际采样就对不上账。所以启动会话时把当时的规划存进 activePlan,图上三条曲线、汇总九项指标、建议六条,全部读这个冻结值。

四种格式的分工是:markdown 给人看(六小节、表格),json 给程序看(保留全部数值不格式化),csv 给表格软件看,text 给终端看。csv 那一支有两处刻意的选择:

return head.join(',') + '\r\n' + rows.map(function (r) { return r.join(','); }).join('\r\n') + '\r\n';

行尾用 CRLF,与 Windows 上的 Excel 一致;文件不带 BOM,因此中文表头在部分工具里会显示成乱码。这是一处真实的取舍:带 BOM 能让 Excel 正确识别编码,但会让很多命令行工具把 BOM 当成第一个字段的一部分。当前实现选了后者,用文本编辑器打开没问题,用 Excel 直接双击打开中文表头会花。第四章的缺陷清单里把它列在报告一节。

报告里所有时间戳都由调用方传入,引擎内部不取当前时间。这条约定写在 sn-report 的文件头,作用是同一份上下文任何时候组装出来都逐字节相同——否则「导出两份报告比对差异」这件事就没法做。

四、鸿蒙稳定性适配

4.1 十处缺陷与真实成因

下面十处都是逐行读源码核出来的,不是猜的。前八条集中在业务代码与业务包清单,后两条属于工程配置与资源。

编号位置现象成因影响
D1sn-util.js十二个导出全项目零调用pctl、maxOf、pad3、slug、hex、lcg、rand01、hash32、pct、avg、sum、copy 都没人用死代码约占工具库一半,读代码时要多绕一圈
D2sn-pair.js设备状态两分钟后必然变离线且不恢复touch 没有任何调用方,lastSeen 停在配对那一刻台账状态列失真,无法反映真实在线情况
D3sn-config.js解析结果里的 order 恒为空数组parse 里声明了 order 变量但从未 push报告用不上「文件里的原始顺序」这一信息
D4sn-session.js引擎缺失时给出的码率区间不自洽兜底写死 3000 / 12000 / 20000,与每像素比特公式口径不同降级状态下的建议看似合理实则错误
D5sn-config.js开箱默认配置即带一条警告max_bitrate 默认 20000,高于 1080p60 H.264 建议上限 16000新用户第一次打开就看到黄色提示,误以为配错了
D6renderer.js第二组之后的准备命令看不见也改不了草稿回填只读 prep[0]界面编辑会静默覆盖多组准备命令
D7package.json两个测试脚本指向不存在的文件第 9、10 行引用的两个 js 在 app 目录里都没有任何一次测试调用直接报错
D8六份 JSON5共十处尾逗号electron 的 build-profile 三处、module 三处、oh-package 一处,web_engine 三者各一处当前构建器容忍,换工具链即失败
D9三处许可证声明关于对话框写 Apache-2.0,app 的 package.json 写 MIT,electron 的 oh-package 为空三处各自维护没有单一来源分发时法律声明自相矛盾
D10两份 string.json应用名仍叫 ElectronAppScope 的 app_name 与 electron 的 EntryAbility_label 都是字面量 Electron,module_desc 仍是 module description桌面图标与任务栏显示 Electron,属于未完成本地化的硬伤

D8 那十处尾逗号的具体分布值得单独列一行,因为它不是一个文件的疏忽:

文件尾逗号数
electron/build-profile.json53
web_engine/build-profile.json51
electron/module.json53
web_engine/module.json51
electron/oh-package.json51
web_engine/oh-package.json51

合计十处。JSON5 允许尾逗号,当前 hvigor 版本也照单全收,所以构建一路绿灯。这类问题的麻烦之处在于它不会在本地暴露,而是在换构建工具、换 IDE 校验器、或者把配置喂给某个只认严格 JSON 的脚本时才炸。

4.2 三条最值得展开的缺陷

D2 值得展开,因为它是一个「函数写好了但没人接」的典型。sn-pair 里 touch 是完整的:

function touch(list, uuid, now) {
  var arr = (Array.isArray(list) ? list : []).slice();
  var i = find(arr, uuid);
  if (i < 0) return arr;
  arr[i] = normalize({ name: arr[i].name, uuid: arr[i].uuid, pairedAt: arr[i].pairedAt, lastSeen: Number(now) || 0, note: arr[i].note });
  return arr;
}

它是纯函数,取一份台账、返回一份新台账,签名与 unpair、rename 一致。问题是渲染层里没有任何一处调用它:配对成功后写的是 pair 返回的 clients,而 pair 里归一化时把 lastSeen 写成了当次的 now。于是状态列在配对瞬间是「在线」,两分钟后判决式地变成「离线」,此后除非重新配对,否则永远不会再变。

修复方向是明确的:把会话推进接上。stepLive 每秒已经在一个定时器里跑,那里顺手把台账整体刷新一次,在线状态就活了。这里还有个细节要一起考虑——如果只刷新当前选中项,未选中的设备仍然会默默过期,所以更稳妥的做法是在会话启动时对台账整体做一次刷新,让「有没有设备在线」这个指标与「会话是否在跑」保持一致。

D5 值得展开,因为它涉及默认值的口径。max_bitrate 的默认值是 20000,而 1080p60 的 H.264 按每像素比特算出来的建议上限是 16000。这两个数字各自都合理,凑在一起就是默认状态必然触发一条警告:

} else if (bits > guide.high) {
  warnings.push('码率上限 ' + bits + ' kbps 高于本分辨率的建议上限 ' + guide.high + ' kbps,多数客户端用不上');
}

这条警告本身没错——20000 的上限确实对多数客户端没用。问题在于它是开箱即现的:用户什么都没动,界面就先黄了一条。默认配置的职责是「拿来就能用且不报警」,一旦默认值本身就触发了校验,用户会把它当成噪音,后面真正需要关注的警告也就一起被忽略了。

处理有两条路。一条是把默认值降到 16000,代价是高分辨率场景下上限偏低;另一条是把这条降级成提示而不参与评分。截图里的 92 分正是被这条扣了 4 分——100 减掉两条警告各 4 分;如果这条不计入分数,开箱应该是 96 分。

D6 已经在 3.3 结尾提过,这里补上修复的形状。当前的回填是:

var prep = (d.prep && d.prep[0]) || { do: '', undo: '' };
setInput('txtPrepDo', prep.do);
setInput('txtPrepUndo', prep.undo);

界面只有一对输入框,所以问题不在于「只回填第一组」这一行代码写错了,而在于界面模型与数据模型不匹配。真要做对,得让 prep 变成可增删的列表:草稿区渲染一组行,每行一对输入框加一个删除按钮,底部一个「再加一组」。这样一来回填自然就是遍历,保存自然就是收集。在单行界面的前提下更保守的做法是:如果草稿里 prep 超过一组,就在界面上明确提示「该应用还有若干组准备命令未在此处显示」,把静默覆盖改写成显式告知。

4.3 平台禁项在样式表上的落地

鸿蒙 PC 上这一批壳应用共同的约束是:不做过渡动画、不用 transform、不用固定定位。sunshine.css 的做法是把这条约束写在文件头,然后在规则区一条都不犯。

702 行的样式表里,transition、animation、@keyframes、transform、position: fixed 这五个词各出现一次到两次,且全部落在文件开头的注释里:

* 平台禁项:不使用 position:fixed、@keyframes、animation、transition、transform,
 * 也不做 text-transform;曲线全部由 canvas 重绘完成

规则区的计数是零——不是「用了很少」,是一个都没有。这一点用全局检索就能验证,五个关键词的命中行号都落在前八行。

替代方案是把动效搬到 canvas 上。会话监控那张图是 960×260 的画布,每秒钟重绘一次:

var dpr = Math.min(3, Math.max(1, window.devicePixelRatio || 1));

设备像素比夹在 1 到 3 之间,是为了在高分屏上线条不糊、同时不让一张 960 宽的画布在后端算出 2880 宽的位图。重绘而不是过渡动画有个额外好处:曲线在任何一帧都是完整状态,截图、导出、报告三者看到的是同一张图。

配色也不写死在渲染代码里,而是从根变量取:

function accent() {
  return getComputedStyle(document.documentElement).getPropertyValue('--accent').trim() || '#4aa8ff';
}

样式表里有 20 个根变量、122 处 var 引用,强调色、网格线、告警色全部走变量。canvas 里取色通过 accent 这个函数读同一个变量,于是改一处样式表,曲线颜色跟着变,不会出现「图表是蓝的、按钮是绿的」这种割裂。取不到再退回一个写死的十六进制值,保证渲染层的行为不依赖 CSS 是否加载成功。

断点只有两处,都很克制:

@media (max-width: 1280px) { ... }
@media (max-width: 1120px) { ... }

两个断点分别对应「双栏变单栏」和「侧栏收窄」。桌面端窗口最小宽度在 main.js 里设成了 1120 与屏幕宽度的较小值,与第二个断点严格对齐——这个对齐是有意的:窗口不能被拖到比最小断点还窄,否则就会落到一个没有写过的布局状态。

还有一处属于「不碰元素 style」这条约束的落地。渲染层里所有可见状态都通过改 className 完成:

n.className = 'tb-state' + (kind ? ' ' + kind : '');

状态条、徽章、面板切换、芯片选中,全部是切换类名,没有一处 element.style.xxx =。这不是风格洁癖:在鸿蒙 PC 的窗口形态下,元素内联样式的高频写入会带来额外的样式重算,而类名切换只在样式表已经算好的规则之间跳转。

4.4 上架前必须完成的替换项

按优先级从高到低:

第一,签名材料。根 build-profile.json5 的 signingConfigs 里,certpath、profile、storeFile 三个字段都是本机绝对路径(指向用户目录下的 .ohos/config),keyPassword 与 storePassword 是加密后的口令串。这份文件对外分发前要么整体换成占位符,要么确认它在忽略列表里。它比同批其他工程更值得警惕,因为它把开发机的目录结构与签名材料位置一并写了出来。

第二,应用标识与文案。AppScope/app.json5 的 bundleName 仍是 com.huawei.ohos_electron,vendor 是 example;AppScope/string.json 的 app_name 与 electron 的 EntryAbility_label 都是字面量 Electron;module_desc 是 module description,EntryAbility_desc 是 description。这四处不换掉,装到机器上桌面显示的就是 Electron。

第三,许可证口径统一。关于对话框写的是本项目遵循 Apache-2.0,app 的 package.json 写的是 MIT,electron 的 oh-package.json5 里 license 是空字符串,web_engine 的 oh-package.json5 写的是 Apache-2.0。四处至少要收敛到一处来源,且与仓库根目录的许可文件一致。这一条在上架审核里会被逐条对读。

第四,测试脚本。package.json 第 9、10 行指向 test-sunshine-engine.js 与 test-sunshine-ipc.js,两个文件都不存在。要么补上这两个脚本,要么把这两行删掉——留着一个一定失败的测试入口,比不写测试更容易误导后来者。

第五,尾逗号十处与 targetSdkVersion 缺失。前者是兼容性隐患,后者意味着 API 版本上限完全依赖 SDK 侧默认,升级工具链时行为会变。compatibleSdkVersion 明确写了 5.0.5(17),targetSdkVersion 却缺席,产物 pack.info 里 target 是 20——这个 20 不是本仓库声明出来的。

第六,docs 目录。electron 下挂了五个说明文件,合计 2086134 字节,其中两个 PDF 各占 1388663 与 620968 字节。这些是开发期参考资料,不属于运行时依赖,打包前应确认不会被打进产物。

五、构建与部署

图 1:冷启动后的主机配置面板。配置来源写着内置默认,配置文件一栏是未打开使用内置默认;四项计数分别为配置项 40、未识别键 0、解析问题 0;网络与端口一栏有 1 条提示,基础端口 47989,派生端口四行依次是 HTTPS 47984、HTTP 47989、Web UI 47990、RTSP 48010;局域网加密停在 1 可选,广域网加密停在 2 强制,心跳 10000,码率上限 20000;底部参数预设未应用,侧栏四个格子分别写着配置默认、应用 0、客户端 0、会话未启动。

图 2:视频与编码面板。编码器一项是未选择,右侧徽章标注 7 项生效;兼容性检查通过,92 分,协商格式 H.264,预计总延迟 26.5 ms,码率建议 10.5 Mbps,被忽略参数无;下面两条提示分别是自动选择按 H.264 加软件编码兜底、码率上限 20000 kbps 高于本分辨率建议上限 16000 kbps;目标输出一栏写 10.5 Mbps,分辨率 1920×1080 与 60 帧已选中。

图 3:关于对话框。开源声明、免责声明、完全开源三段,分别写明 Electron 基于 MIT、本项目遵循 Apache-2.0、不监听端口也不编码视频流。这三段里说的「不监听端口」与 main.js 的 unsupported 第一条是同一件事。

5.1 产物构成与构建日志

构建输出在 electron 模块的 build/default/outputs 目录下,两个 hap 加一份元数据:

文件字节换算
electron-default-signed.hap195417759186.36 MB
electron-default-unsigned.hap193958346184.97 MB
pack.info752—

两个 hap 相差 1459413 字节,这个差值就是签名段的大小,与包体总量相比不到百分之一。pack.info 只有 752 字节,里面写清了 compatibleVersion 17、targetVersion 20、buildMode Release,以及三个 ability、两个 extensionAbility 与 deviceType 数组 2in1 与 tablet。

mapping 目录下还有一份 sourceMaps.map,572033 字节。它是 Release 构建下混淆映射的产物,只用于把线上堆栈还原回源码行号,不应该随包发布——但它在构建目录里存在这一事实,提醒我们导出产物时要按文件白名单而不是目录整体拷贝。

构建日志不在 outputs 目录下,而在模块根的隐藏目录里:.hvigor/outputs/build-logs/build.log。这份日志 511873 字节、5869 行,里面 BUILD SUCCESSFUL 出现 3 次、FAILED 出现 0 次、[ERROR] 标记 0 处、[WARN] 标记 9 处。三次成功对应一次首次构建加两次增量重建(改文案、改样式后各一次),九条警告集中在依赖解析阶段,没有一条来自我们的业务代码。

产物目录里还有一份 stripped_native_libs,与 libs 目录一一对应,这是下一节体积话题的直接证据。

5.2 体积构成与原生库

打包进 hap 的原生库只有四个,全部在 libs/arm64-v8a 下:

库字节占 hap
libelectron.so16747191285.70%
libadapter.so26212001.34%
libffmpeg.so21815281.12%
libc++_shared.so18256240.93%
合计17410026489.09%

四个库占了 195417759 字节的 89.09%。剩下的百分之十一里,鸿蒙侧的 ability 与资源文件占大头,真正属于这个应用的业务代码——app 目录那 12 个文件、209571 字节——只占包体的 0.107%。这个比例说明了壳应用的成本结构:包体积几乎完全由 Electron 运行时决定,业务代码写多写少对安装包没影响,写得好不好全看运行时的内存与启动时间。

剥离前后只有一个小库变了:

库libs/arm64-v8astripped_native_libs变化
libelectron.so167471912167471912无
libadapter.so26212002621200无
libffmpeg.so21815282181528无
libc++_shared.so18256241334688减 490936,减 26.9%

三个大库剥离前后字节数不变,只有 libc++_shared 掉了 490936 字节。原因是前三个在构建时已经是剥离过的发行版,符号表本来就不在了。这也解释了为什么给它们配置 strip 不会带来任何收益。

与 lib.unstripped 目录对比更能看出差距:libelectron 在 lib.unstripped 里是 1143668440 字节,装进包里的是 167471912,瘦身比约 6.83 倍;libadapter 从 15494016 到 2621200,约 5.91 倍。一个多 GB 的未剥离库能被装进一百多 MB 的包,靠的正是当初构建时就把调试符号分出去。这也意味着排查崩溃时必须手上有一份对应版本的 lib.unstripped,光看包里的 so 反推不出函数名。

5.3 权限声明与设备形态

web_engine 的 module.json5 是本工程里最长的一份配置,176 行,其中绝大篇幅是权限声明。requestPermissions 数组里一共有 26 条,分两类:

分类条数特征
无 reason 字段15直接列出权限名
带 reason 与 usedScene11reason 是中文说明,usedScene 全部指向 FormAbility

两类并存不是一个好信号。带 usedScene 的十一条显然是从母版拷贝过来的:它们声称这些权限用在 FormAbility(卡片)场景,而这个应用根本不是卡片形态。usedScene 里的 abilities 字段应该写真正申请该权限的 ability 名,全部写成一个与本场景无关的名字,等于告诉审核员这份声明是模板。

同一份文件里还有两处容易被忽略的细节。一处是被注释掉的 WEB_NATIVE_MESSAGING(与 Electron 的扩展能力相关,当前壳不走这条路径);另一处是 definePermissions,声明了一个 LOCK_WINDOW_CURSOR 自定义权限。后者属于内部约束,不上报系统,但仍占审查篇幅。

设备形态声明在两处:electron 的 module.json5 与根 build-profile 里都写 2in1 与 tablet,产物 pack.info 里的 deviceType 数组与声明一致。这一点在本工程里是对的——没有出现声明一套、打包另一套的情况。但也正因为声明了两类设备,界面的最小宽度硬约束就显得重要:表格在平板形态下会被挤压,第二断点的 1120 只能保证不再窄,不能保证表格内容不被截。

六、常见问题与解决方案

Q1 什么都没改,打开主机配置面板就看到一条黄色提示,是不是默认配置本身坏了?

问题现象:冷启动后徽章显示 1 条提示,点进校验结果看到的是编码器为自动选择那一句;转到视频与编码面板,兼容性检查虽然写「通过」,分数却只有 92,下面还挂着第二条关于码率上限过高的提示。

根因分析:这两条提示都是真实存在的,而不是错报。第一条来自 compat 函数对空编码器值的短路:留空代表自动选择,代码按 H.264 加软件编码兜底给出一整套评估,同时用一条警告把不确定性说清楚。第二条来自 evaluate:默认 max_bitrate 是 20000,而 1080p60 的 H.264 按每像素比特算出来的建议上限是 16000,20000 确实超出了。两条各扣 4 分,所以通过状态下也只有 92 分。

解决方案:不需要去修「通过却不满分」这件事,分数本来就是扣分制的反馈。要做的是把这两条当成待办:选定一个编码器,第一条自然消失;把码率上限降到 16000 以内或换成更高分辨率,第二条也会消失。两条都清掉后分数回到 100,此时的分才是干净的分。

教训:默认配置一旦触发自己的校验,校验就失去了信号价值。在给键表定默认值时,应该拿默认值跑一遍全部校验,确保开箱状态是零错误的——零警告很难做到,至少要做到「默认值不触发警告」。

Q2 保存之后,配置文件里那几行不认识的键去哪了?

问题现象:手写的 sunshine.conf 里带了几行这份壳不认识的键,在面板上能看到的只有「未识别键」那个计数是 3,具体是哪三行找不到;另存一份之后,那三行还在,但用户不确定是不是原位置。

根因分析:解析时未知键被单独收进 extra 数组,不参与类型收敛,也不会在面板上逐条列出——renderConfig 只把 extra.length 写进一格计数。序列化时它们会被写到末尾而不是原位,因为 serialize 是按 GROUPS 声明的顺序拼的,未知键没有顺序信息可用。这与 D3 有关:parse 里本来要记录文件中的原始顺序,但 order 变量声明后从未被写入。

解决方案:短期的做法是接受这个行为并把它写进说明——未知键会保留但会移到文件末尾。真正的修复是把 order 补上:解析时每遇到一个键就 push 到 order,序列化时先按 order 排已知键,未知键保持在它原来的相对位置。这样「只改了三个值、导出的 diff 却是一片」的情况就不会发生。

教训:配置文件编辑器的基本承诺是「没动的地方一个字节不变」。做到这一点靠的不是小心翼翼地保留,而是解析阶段就把原位信息存下来,并在序列化阶段用上它。

Q3 在界面上把准备命令删了,保存之后它又回来了。

问题现象:一个应用原本有两组 prep,在草稿区把第一组的 do 与 undo 清空,点保存,重新打开这条应用,第一组空了但第二组还在,界面上依然只显示那一对空输入框。

根因分析:界面上只有一对输入框,回填时只读 prep[0],读取时也只写回 prep[0],中间那几组在往返过程中无人认领。它们既不在界面上显示,也没有被删除,只是默默跟着 draft 走,于是保存时又整体写回了清单。

解决方案:如果要支持多组,就得把界面模型改成列表,而不是在单行界面上打补丁。退一步的最低要求是:当草稿里的 prep 超过一组时,在草稿区给出显式提示,告诉用户还有若干组不在当前视图内、保存后会原样保留。让不可见的改动变成可见的告知,比让它静默发生好得多。

教训:界面模型与数据模型不一致时,缺失的那一部份数据不会消失,它只是在用户看不见的地方被搬运。只要存在「数据有而界面无」的字段,就必须在界面上明确告知它的存在。

Q4 编码器留空时那一整套评分能信吗?

问题现象:没选编码器时,面板照样给出 H.264、26.5 ms、92 分、10.5 Mbps 这一整套结论,看上去跟真的一样。

根因分析:compat 对空值有一条短路,注释写得很明白:留空是合法的自动选择,按兜底编码器评估,但把不确定性说清楚。所以那套数字是按软件编码加 H.264 算出来的,不是按用户真实硬件算的。每一个系数都能对上:基准 14 ms、未开 zerolatency 加 2、网络段 7、解码段 3.5。

解决方案:看徽章颜色。编码器一栏在未选择时是 warn 色而不是 ok 色,这就是在提醒结论是兜底的。要看真实结论,先在编码器芯片里选一个具体项,再或者把显卡名填进配置,推荐函数会给出理由与备选。

教训:降级本身不可避免,降级不能让界面看起来什么都没发生。这个工程的做法是对的——降级后仍然给结果,但把降级状态写进告警与颜色,让用户知道自己在看什么。

Q5 同样的参数,换一台机器跑,曲线完全不一样。

问题现象:A 机器上跑出来的会话曲线尖峰总在第 17、34、51 步,换 B 机器后这些尖峰的位置全变了,汇总数字也对不上。

根因分析:这条曲线的每一点都从 seed 派生,而 seed 没有暴露在界面上。默认创建时用的是固定种子,但如果调用方传入的时间戳或其他机器的值,整条链就会分叉。另一种情况是历史被裁剪:跑到一百多秒之后 history 只留最后 120 条,这时候开始看汇总,得到的统计区间与刚开始跑时不一样。

解决方案:报告里会写上种子与采样数,比对新旧两份报告时先把这两个字段看清楚。如果种子相同而曲线不同,那就要查是不是中间重启过——重启会把 tick 归零,而 seed 的新一轮派生从新的 tick 开始。要让两次完全可比,最稳的做法是把会话跑到相同步数再导出。

教训:可复现性的承诺不仅包含「随机量从种子来」,还包含「种子本身可记录、可传递」,否则用户复现不了时根本不知道该对什么。

Q6 导出的 CSV 用 Excel 双击打开,中文表头是乱码。

问题现象:导出一份 csv,用文本编辑器打开正常,用 Excel 直接双击打开,第一行表头全是问号与方块;但用 Excel 的导入向导选 UTF-8 再开又正常。

根因分析:buildCsv 没有写 BOM,而 Excel 在双击打开时不会自动猜测 UTF-8,它按系统默认编码读。这跟 D8 里那十处尾逗号是一类问题:格式上合法,只是对读者不友好。

解决方案:在 buildCsv 的返回值前面加一个 BOM 字符即可,一行代码。代价是某些命令行工具会把 BOM 当成第一个字段的一部分,比如 awk 取第一列会多出不可见字节。所以更稳的做法是两条路都提供:一个无 BOM 的给程序吃,一个带 BOM 的给 Excel 吃。

教训:文件格式的默认值面向谁,决定了你要不要在开头加那几个字节。导出功能最好在按钮上就把读者说清楚,而不是让用户在 Excel 里发现乱码后再回头查。

Q7 装到机器上,桌面显示的还是 Electron。

问题现象:hap 装完,桌面图标下面的名字是 Electron,任务栏、权限弹窗里的应用名也全是 Electron。

根因分析:应用名不读 package.json,而是读 AppScope/string.json 的 app_name,而这一项在本工程里是字面量 Electron;EntryAbility 的入口标签读 electron 模块下 string.json 的 EntryAbility_label,同样是 Electron;两个描述字段仍是母版里的 module description 与 description。这四份文案都是母版直传,从未改过。

解决方案:改 string.json 里的这四处,同时把 bundleName 从 com.huawei.ohos_electron、vendor 从 example 换成正式标识。改完必须重新构建,因为应用名在编译期就进了资源索引,热更新改不到。

教训:显示在桌面与系统 UI 上的文案不是业务代码的一部分,它不会因为业务逻辑写得好就自动正确。这类文案要在第一次构建前就列成清单逐项打勾,而不是等到上架前才去翻。

七、总结

这篇实战把 Sunshine 串流控制台从八个 IPC 通道到两个 hap 产物完整走了一遍。它的结构可以概括成一张表:

层次内容规模
主进程八个 IPC 通道、路径纪律六函数、十二条错误码355 行
渲染层状态机、七面板、canvas 曲线、校验与报告接线1721 行
引擎层七个纯函数模块,40 键配置表、编码器评估、台账、遥测2306 行
界面七个面板、153 个元素 id、一个 canvas555 行
样式20 个主题变量、122 处变量引用、五项平台禁项全为 0702 行
产物签名包与未签名包,四个原生库占 89.09%195417759 字节

三条关键经验值得单独记下来。

第一,同一个数字只能有一个出口。这个工程里 92 分、10.5 Mbps、26.5 ms 这三个数字在面板、报告、校验三处出现,三处读的都是同一个 evaluate 的返回值;格式也一样,全部走 sn-util 的 fmt 与 kbps。唯一的分歧出现在 pctl 与 sn-session 里那一份 p95 上——两处各自实现了同一套不插值逻辑(sn-util 那一份按 D1 是零调用),代码重复但口径一致,属于可以接受的重复。

第二,配置的往返稳定要靠三条规则同时成立:按声明顺序排、默认值省略、未知键保留在末尾。三条少一条就会出现「我只改了一个值、导出的 diff 却是一整片」。这三条不是写一次就一劳永逸的,每加一个键都要回头看一遍序列化会不会把它写到不该写的地方。

第三,平台约束要能以可统计的方式落地。样式表 702 行里,transition、animation、@keyframes、transform、position: fixed 五项在规则区全部为 0,不是「记得别用」,而是每次都能检索出来;曲线全部由 canvas 每秒重绘一次,强调色通过 accent 函数从根变量取,与样式表同源。

最后是四件上架前必须做的事:把 AppScope 的 app_name 与 electron 的 EntryAbility_label 从 Electron 换成应用真名,并补上 module_desc 与 EntryAbility_desc 的真实描述;把 package.json 的 MIT、关于对话框的 Apache-2.0、两份 oh-package.json5 里的空值与 Apache-2.0 统一成一个许可证并附上文件;把 bundleName 从 com.huawei.ohos_electron、vendor 从 example、versionCode 从 1000000 换成正式标识;把根 build-profile.json5 里含本机绝对路径与加密口令的 signingConfigs 换成占位符或确认它不在分发范围内。四件事都不涉及业务逻辑,但没有一件可以在评审阶段蒙混过去。

Logo

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

更多推荐