鸿蒙 PC 上用 Cordova 复核诊断包,解压成功之后还要对三份文件鸿蒙 PC 上的 Tauri 库存文件核验,把截断定位到 0x0E
Cordova OpenHarmony框架仓 · 诊断包复核完整源码 · 鸿蒙 PC 开发者社区
前言
交班时收到一份诊断 ZIP,解压器弹出成功,接班人还得确认日志、清单和交接说明有没有完整拿回来。只看归档大小,连丢的是哪份文件都无从知道。我在鸿蒙 PC 上用 Cordova 做了一个诊断包复核台,让同一份回执记录源字节、解压后的字节和实际对比结果。三个文件都是程序生成的固定样例,测试不会接触现场设备的数据。
我把故意失败的一次检查放进同一套验收。先让正常包出一张全绿回执,再交给系统一个不是 ZIP 的样例,最后回到正常包。这样既能检查解压接口确实报告失败,也能看到界面有没有继续显示上一份通过结果。失败后的回执如果不干净,值班人员就可能把旧结果转发给接班人。
先让上一张回执失效
在 MateBook 14 本机编译并签名的 1.0.1 中,点「生成 ZIP」,顶部得到原文件合计 2,934 B 和归档 539 B。此时第三项仍是破折号,说明压缩完成后还没有作逐文件承诺。点「解压并比对」,右侧数字才变成 3 / 3。表里分别核对传感器日志、JSON 清单和交接文本,源文件和恢复文件都是 2,800 B、55 B、79 B。


然后点「检查无效包」。系统返回 900003,表格撤下三行已通过的旧回执,只留下这次没有逐文件结果的提示。原文件体积和正常 ZIP 体积继续显示,因为它们属于本轮已生成的归档,和这次解压是否通过是两个字段。再次点「解压并比对」时不需要重做 ZIP,原归档仍能返回 3 / 3。换成窄窗,再执行一次失败和一次恢复,日志同样先报 900003,再报 bytesMatch=true 和 archiveRoot=flat。


| 本机环节 | 检查的证据 |
| 生成正常归档 | 样例原文件 2,934 B,正常 ZIP 539 B |
| 解开并读取 | 输出为 flat,三个恢复文件分别为 2,800、55、79 B,与源文件逐字节一致 |
| 检查无效包 | 错误 900003,无恢复结果,当前通过数清空 |
| 回到正常归档 | 仍使用原 ZIP,三个文件重新比对通过 |
早期 1.0.0 的模拟器记录中,原文件仍是 2,934 B,ZIP 为 536 B,文件也都能恢复。在这次本机复测里,只核对了 539 B 的实际产物和恢复结果。那三字节没有做 ZIP 容器层面的差异追溯,不能反推是哪一项压缩元数据不同。做交接验收时先清楚本次要证明的是内容恢复还是归档逐字节一致,这两个指标应分别设计数据。
下方保留两端早期实录和 GIF,验证的是当时 1.0.0 的功能。上面的截图、数值和错误日志来自本次 MateBook 14 的本机重建版。
MateBook 14 真机压缩、解压和失败后恢复。平均 4.86 fps,业务段有效帧率 5.00 fps,无音轨。依次显示 ZIP 体积、三份回执、错误码和正常回执。
MateBook Pro 模拟器 ZIP 复核实录。使用连续截图,平均 3.57 fps,业务段有效帧率 3.56 fps,无音轨。保留与真机相同的四步操作。
新的连续演示先生成归档,随后看三行逐字节通过。接着检查无效样例:900003出现,旧的3/3和三行绿字都撤下。最后直接复核原来的正常ZIP,三行再次通过。三份源样例没有重写,失败只影响本次解压回执。

录制请求上限60 fps,实际可变帧率录像平均13.25 fps。GIF保留120帧、9.14秒,平均13.13 fps,没有复制帧或插帧。主要变化是回执替换,两次点击之间的阅读停留按真实时间保留。
本轮也把同一本机构建目录的1.0.1 HAP装进模拟器,重新生成、比对、失败和恢复。模拟器这次生成536B ZIP,真机为539B,但两端恢复出的三份文件均为2800、55、79B且逐字节一致。这里只确认内容恢复一致,仍没有对ZIP容器的三字节差异作原因归属。下图是本轮实测,不借用早期视频来证明当前包。


从 Web 按钮到沙箱里的三份文件
业务页面等 deviceready 后开放「生成 ZIP」,因为之前 Cordova 桥还没就绪。每个按钮给原生插件的只是自己对应的动作名。动作进到 DiagnosticArchive 后,原生插件在应用的缓存目录创建本次工作目录,按固定模板写入三份源文件,同时生成正常 ZIP 和作为失效对照的文本文件。这里不用让页面提交路径,也不用浏览用户目录。需要导入真实诊断包时,应另做文件选择入口,并给文件来源、允许的大小与输出位置设置明确范围。
原生写文件使用 UTF-8 字节数据,并核对实际写入长度。读取则先查磁盘文件长度,然后分配缓冲区,核对 read 的返回数量。任何一次短读或短写都不能作一致通过。文本包含中文也按 UTF-8 第一个字节到最后一个字节核对,实际 79 B 不是页面上看见的字符数。比较过程先判断字节数,再逐位置检查相等。同长度只是前置条件,里面有一个字节内容不同也应返回差异。
每次复核先单独创建 verify-序号 目录,再把 ZIP 解出。首个文件失败时,清理的只是本次输出目录,源文件和已生成 ZIP 仍可做下一次验证。代码分别读取最外层有 source 目录和直接平铺的两种结构。实际本机返回的是 flat。这个区别在日志里留档,免得原生 zlib 已经正常解出文件,复核却固定从错误的子目录去找。此次验证针对三份已知小样例,比较时一次读完整文件。常规产品要处理很大的日志,适合复用读取循环分段比对,并对整个任务设定可见的上限。
import { common } from '@kit.AbilityKit';
import { util } from '@kit.ArkTS';
import { BusinessError, zlib } from '@kit.BasicServicesKit';
import { fileIo } from '@kit.CoreFileKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { CallbackContext, CordovaPlugin } from '@cordova-ohos/ohos/Index';
interface Fixture {
name: string;
content: string;
}
interface FileCheck {
name: string;
sourceBytes: number;
restoredBytes: number;
identical: boolean;
}
const tag = 'DiagnosticArchive';
const fixtures: Fixture[] = [
{ name: 'sensor.log', content: '2026-11-14T09:16:30 sensor=P03 status=normal value=26.4\n'.repeat(50) },
{ name: 'manifest.json', content: '{"batch":"DG-240","operator":"fixture","sensor":"P03"}\n' },
{ name: 'handover.txt', content: '模拟设备巡检记录\n检查编号 DG-240\n核对传感器与交接清单。\n' },
];
export class DiagnosticArchive extends CordovaPlugin {
private workDir = '';
private running = false;
private attempt = 0;
execute(action: string, _args: ESObject[], callback: CallbackContext): boolean {
if (action !== 'pack' && action !== 'verify' && action !== 'verifyInvalid') {
return false;
}
if (this.running) {
callback.errorByString('BUSY');
return true;
}
this.running = true;
this.perform(action, callback);
return true;
}
private fileBytes(path: string): Uint8Array {
const handle = fileIo.openSync(path, fileIo.OpenMode.READ_ONLY);
try {
const size = fileIo.statSync(handle.fd).size;
const buffer = new ArrayBuffer(size);
if (fileIo.readSync(handle.fd, buffer) !== size) {
throw new Error('SHORT_READ');
}
return new Uint8Array(buffer);
} finally {
fileIo.closeSync(handle);
}
}
private write(path: string, content: string): void {
const encoded = new util.TextEncoder().encodeInto(content);
const bytes = new ArrayBuffer(encoded.byteLength);
new Uint8Array(bytes).set(encoded);
const file = fileIo.openSync(path, fileIo.OpenMode.CREATE | fileIo.OpenMode.WRITE_ONLY | fileIo.OpenMode.TRUNC);
try {
if (fileIo.writeSync(file.fd, bytes) !== bytes.byteLength) {
throw new Error('SHORT_WRITE');
}
} finally {
fileIo.closeSync(file);
}
}
private async openArchive(action: string, callback: CallbackContext): Promise<void> {
if (!this.workDir) {
throw new Error('PACK_FIRST');
}
const folder = this.workDir + '/verify-' + (++this.attempt).toString();
fileIo.mkdirSync(folder);
const zip = this.workDir + (action === 'verifyInvalid' ? '/invalid.zip' : '/diagnostics.zip');
try {
await zlib.decompressFile(zip, folder);
const entries = fileIo.listFileSync(folder);
const root = entries.includes('source') ? folder + '/source' : folder;
const files: FileCheck[] = [];
for (const item of fixtures) {
const expected = this.fileBytes(this.workDir + '/source/' + item.name);
const restored = this.fileBytes(root + '/' + item.name);
files.push({
name: item.name, sourceBytes: expected.length, restoredBytes: restored.length,
identical: expected.length === restored.length &&
expected.every((byte: number, index: number) => byte === restored[index]),
});
}
const passed = files.every((item: FileCheck) => item.identical);
hilog.info(0, tag, 'action=%{public}s count=%{public}d bytesMatch=%{public}s archiveRoot=%{public}s',
action, files.length, passed ? 'true' : 'false', root === folder ? 'flat' : 'source');
callback.successByString(JSON.stringify({ state: passed ? 'verified' : 'different', files }));
} finally {
this.cleanup(folder);
}
}
private async perform(action: string, callback: CallbackContext): Promise<void> {
try {
if (action === 'pack') {
const context = this.cordovaWebView?.getUIContext().getHostContext() as common.UIAbilityContext;
if (!context) {
throw new Error('NO_CONTEXT');
}
if (this.workDir) {
this.cleanup(this.workDir);
this.workDir = '';
}
this.workDir = context.cacheDir + '/diagnostic-zip-' + Date.now().toString();
fileIo.mkdirSync(this.workDir + '/source', true);
const source = this.workDir + '/source';
let rawBytes = 0;
for (const item of fixtures) {
const path = source + '/' + item.name;
this.write(path, item.content);
rawBytes += fileIo.statSync(path).size;
}
const zip = this.workDir + '/diagnostics.zip';
await zlib.compressFile(source, zip, { level: zlib.CompressLevel.COMPRESS_LEVEL_DEFAULT_COMPRESSION });
this.write(this.workDir + '/invalid.zip', 'This fixture is plain text, not a ZIP archive.\n');
const zipBytes = fileIo.statSync(zip).size;
hilog.info(0, tag, 'packed rawBytes=%{public}d zipBytes=%{public}d', rawBytes, zipBytes);
callback.successByString(JSON.stringify({ state: 'packed', rawBytes, zipBytes }));
} else {
await this.openArchive(action, callback);
}
} catch (error) {
const detail = error as BusinessError;
hilog.error(0, tag, 'action=%{public}s code=%{public}d %{public}s', action, detail.code ?? 0, detail.message);
if (action === 'pack' && this.workDir) {
this.cleanup(this.workDir);
this.workDir = '';
}
callback.errorByString(JSON.stringify({ action, code: detail.code ?? 0, message: detail.message }));
} finally {
this.running = false;
}
}
private cleanup(path: string): void {
try {
fileIo.rmdirSync(path);
} catch (error) {
const detail = error as BusinessError;
hilog.warn(0, tag, 'cache cleanup returned %{public}d', detail.code ?? 0);
}
}
onDestroy(): void {
if (!this.running && this.workDir) {
this.cleanup(this.workDir);
this.workDir = '';
}
}
}
页面只接收 packed、verified、different 或错误描述,用以更新数字和逐行回执。调用期间三个入口暂时禁用,插件自身也有运行中检查。这个设计的目的,是让一次按钮操作和一次回执建立对应关系;同一个归档的旧成功不要覆盖本次错误。解压无效时撤下表格行和通过计数,保留已准备的正常源文件和压缩包,这就是能立即回到正常包做复测的原因。
'use strict';
const byId = (id) => document.getElementById(id);
const pack = byId('pack');
const verify = byId('verify');
const invalid = byId('invalid');
const status = byId('status');
const listing = byId('files');
let packed = false;
function showStatus(message, error = false) {
status.textContent = message;
status.classList.toggle('error', error);
}
function setBusy(busy) {
pack.disabled = busy;
verify.disabled = busy || !packed;
invalid.disabled = busy || !packed;
}
function fillRows(files) {
listing.replaceChildren();
for (const file of files) {
const row = listing.insertRow();
for (const value of [file.name, file.sourceBytes, file.restoredBytes]) {
row.insertCell().textContent = value;
}
const match = row.insertCell();
match.textContent = file.identical ? '一致' : '不一致';
match.classList.add(file.identical ? 'ok' : 'bad');
}
}
function run(action) {
setBusy(true);
showStatus(action === 'pack' ? '正在本地准备样例并压缩…' : '正在原生端解压…');
cordova.exec((result) => {
const data = JSON.parse(result);
if (data.state === 'packed') {
packed = true;
byId('raw').textContent = data.rawBytes + ' B';
byId('size').textContent = data.zipBytes + ' B';
byId('passed').textContent = '—';
listing.replaceChildren();
const remaining = listing.insertRow().insertCell();
remaining.colSpan = 4;
remaining.textContent = '已生成 diagnostics.zip,仍需单独解压复核。';
showStatus('生成完成,可选择正常包或无效样例。');
} else {
fillRows(data.files);
const matched = data.files.filter((file) => file.identical).length;
byId('passed').textContent = matched + ' / ' + data.files.length;
showStatus(matched === data.files.length ? '三个文件全部通过逐字节复核。' : '部分解压文件与原本不同。');
}
setBusy(false);
}, (result) => {
let reason = result;
try {
const error = JSON.parse(result);
reason = error.code + ' · ' + error.message;
} catch { /* An ordinary Cordova error may already be text. */ }
if (action === 'pack') {
packed = false;
}
byId('passed').textContent = '—';
listing.replaceChildren();
const rejected = listing.insertRow().insertCell();
rejected.colSpan = 4;
rejected.textContent = '这次操作未得到逐文件结果。';
showStatus((action === 'pack' ? '生成失败:' : '解压未通过:') + reason, true);
setBusy(false);
}, 'DiagnosticArchive', action, []);
}
document.addEventListener('deviceready', () => {
setBusy(false);
showStatus('就绪。先生成内置的三文件样例归档。');
pack.onclick = () => run('pack');
verify.onclick = () => run('verify');
invalid.onclick = () => run('verifyInvalid');
}, { once: true });
同一台鸿蒙电脑上的构建和安装记录
把 CordovaDiagnosticZip 源码归档放进 MateBook 14 的文档目录,本机解包并打开工程。用 DevEco Studio 查入口模块、Cordova 宿主和 entry/src/main 的资源目录。www 里有 index.html 和 archive.js,ArkTS 插件在 entryability 目录,原生 zlib 和文件读写调用均从这个工程编译。工程中 Cordova 的 HAR 子模块版本为 14.0.2;页面夹带的 cordova.js 内部构建标签显示 14.0.1。遇到版本记录不一致时,应当分别写出模块与网页资源的实际标签。
tar -xzf cordova-diagnostic-zip-source.tar.gz
cd CordovaDiagnosticZip
uname -m
ohpm install --all
hvigorw --mode module -p product=default -p module=entry@default -p buildMode=debug assembleHap --no-daemon
ls -l entry/build/default/outputs/default/*.hap
用 OhPM 准备本地依赖、Hvigor 组装 HAP,本次首次 43 项任务耗时 16.723 秒,未签名 HAP 为 23,174,828 字节。IDE 目标选择「此电脑」时直接装未签名包,系统返回 9568320。通过运行输出进入签名配置,生成本项目的调试签名,再由 DevEco 本机组装并安装 entry-default-signed.hap。签名包为 23,439,948 字节。装机查询 com.aasd23.ugccordovadiagzip 得到 1.0.1 和版本代码 1000001,入口启动后进入前面三组复测。
| 对象 | 版本及范围 |
| 本机开发和实测 | HUAWEI MateBook 14(MNTXM-24B),HarmonyOS 7.0.0,软件版本 7.0.0.115(SP11C00E103R12P2patch01),API 26.0.0,aarch64 |
| 原生工具和框架 | 鸿蒙版 DevEco Studio 26.0.0.220,Cordova OpenHarmony 原生模块 14.0.2 |
| 工程目标 | HarmonyOS 6.1.1(API 24),2in1,本机签名调试包 |
| 本轮模拟器1.0.1 | MateBook Pro 2in1,管理器配置HarmonyOS6.1.1(API24);实际运行软件6.1.0.125(SP12DEVC00E47R1P3),API24,x86_64。同一本机构建1.0.1 HAP,536B归档恢复3/3,无效包900003后可恢复;旧视频仍为1.0.0。 |

回执想做到可复查,还要留意失败发生在哪个阶段。压缩后打不开时,原生错误描述能告诉接班人是压缩格式或文件不完整。能打开,但某份恢复文件长度与源数据不同,则应直接定位到表中的文件名。长度吻合但字节有差异也是另一种线索,应继续核对取到的是哪份源文件。在这个演示中最后一种结果由 identical 的布尔值表达,真机给定样例只覆盖了符合预期的三份恢复和无法解开的负对照。没有复测长度相同但字节被改动的输入,这个分支仍需用自己的数据验证。
应用为每次解压单独编号,新一轮生成则创建新的工作目录。排查重试时应同时检查原生动作名和写入顺序。比如日志明确写着 verifyInvalid 报 900003,说明失败发生在负对照这一步。下一条 verify 成功属于正常 ZIP 的另一轮尝试,即使界面重用了同一张表格,也不该把两条记录拼成一次操作。若要做批量导入,回执最好附上源归档标识和尝试序号,便于将错误、日志与实际归档对应。
FAQ
为什么只生成 ZIP 还没有 3 / 3? 生成阶段只负责写入与压缩。复核还要新建输出位置、解压、逐文件读取再比较。上游在打包完成后马上显示通过,会让接班人误以为归档已经展开核对。
900003 出现后,为什么可以用同一个正常包继续? 无效样例是另外一个文件,系统拒绝后清的是这一次尝试的输出,不会改正常 ZIP 和三份源文本。实际界面先撤掉旧回执,下一次正常归档能够重新给出三条新结果。
三份样例通过,能说明什么? 能确认这次列出的三个固定文件恢复后字节一致。当前回执只查这份固定清单,没有声明它验证了任意诊断包的所有条目。将来要接受外部归档时,应先定义清单与归档内容怎样一一对应,并为多项、少项和未知项目分别设计验收。
总结
生成压缩包、解压和核对各有一份自己的结果。真机上,539 B 的正常 ZIP 恢复出三份原字节,无效文件让当次回执失效,原归档随后还能通过。项目把这些不同状态放在同一窗口里,接班人能看出现在可以继续用哪些材料,也能看见发生错误时该回到哪一步。
更多推荐


所有评论(0)