准备把HarmonyOS应用交给发布同事时，文件名往往都很像：phone-release.app、tablet-release.app、preview-release.app、hotfix-release.app。它们都带着“release”，也都来自同一套流水线目录，但这并不保证四个文件指向同一应用身份，更不能证明上传到AppGallery Connect（AGC）的那个文件正是测试同事确认过的二进制。单凭“文件存在、后缀正确、版本文案对得上”，无法拦住拿错包或回执过期这类工程事故。

本文把检查提前放到发布交接以前，只设计一套离线门禁ReleaseReceiptGate。它读取一个由可信构建步骤生成的候选回执，计算本地文件的SHA-256，与回执中的摘要和目标应用包名逐项对账。这个工具不会解析真实APP内部的HAP，不验签，不上传到AGC，也不代替应用市场的包有效性检查。它要解决的范围更窄：同一批候选文件中，哪些能够继续进入后续的官方检验环节，哪些应该暂时扣住并说明差异原因。

固定样例的任务号为REL-1010-19，目标包名com.example.weeklyboard，内部发布标识1.8.4。四个候选文件中，P01和P02通过，P03因回执包名是com.example.weeklyboard.debug而被拒绝，P04因本地计算摘要与构建回执摘要不一致而被拒绝。汇总为四个候选、两个通过、两个阻断，状态RELEASE_HOLD。以下数字与日志是演示约定，不表示这些文件是真正可安装的APP包。

一、不要把三个“通过”画成一个对勾

发布链路里至少有三层不同的验证。第一层是业务侧的交接身份：目标应用是什么、文件是不是同一批次、哈希有没有变化。第二层是构建产物的结构与签名：APP包内部结构、证书、Profile及其他真正需要工具解析的细节。第三层是AGC平台的上传和发布审核。第一层通过不推出第二层通过，第二层通过也不保证第三层审核通过；如果用一个绿色“成功”横跨三层，就会让负责人误解工具到底做了多少工作。

华为官方2026年5月19日更新的应用身份配置资料指出，工程AppScope/app.json5中的bundleName需要和AGC创建的应用包名对应。另一个关于选择待发布包的官方文档说明，包上传并通过平台的基本有效性检查之后，才会进入选择待发布包的过程。这两条事实只说明身份和平台流程如何关联，不等于Node.js脚本能够查询AGC后台，更不代表文件名包含release就符合市场审核规定。

因此本例设三个明确未执行的状态：AGC_UPLOAD=NOT_RUN、APP_PARSE=NOT_RUN、SIGNATURE_VERIFY=NOT_RUN。这三个字段在主界面和差异诊断页都出现。它们不是无关紧要的小字，而是交付声明的一部分。审核者看到RELEASE_HOLD，应理解为本地已发现两处不能忽略的问题；看到NOT_RUN，则知道真实平台和真实制品验证仍需后续执行。

另一个常见误区是“先比文件体积，一样大就不用算哈希”。体积只是一项快速可读元数据，两段不同的二进制完全可能长度相同。即使两份文件的SHA-256摘要一致，也只能说明按该摘要机制比较的字节内容相同，不能由此推出发行者身份、运行行为或审核资格。哈希校验与数字签名验证是两种不同的安全问题，不应在界面上混用“签名不一致”与“摘要不一致”。

二、回执到底来自哪一步，决定了它是否可信

ReleaseReceiptGate不从APP文件名猜包名，而是使用可信构建步骤输出的sidecar回执。回执是和候选文件一一对应的独立JSON记录，包含候选ID、文件相对路径、期望包名、内部发布标识、构建任务标识和期望SHA-256。由哪个CI作业签发回执、谁有权限改写、生成后是否允许覆盖，必须由实际团队的构建规范控制。这部分信任链不能靠Demo里一个receipt.json字段自动成立。

为什么不在工具里直接解包.app并寻找某个JSON字段？因为这需要确认当前使用的APP打包结构、支持的解析工具与签名校验方法，不能用unzip能打开就推断所有APP变体都可以一样处理。本文没有调用这些平台工具，反而明确把APP_PARSE写成NOT_RUN。如果将来增加真实解析阶段，应使用对应版本的官方DevEco工具，独立生成验证日志，并把新阶段结果与本地回执区分保存。

这里的四份.app只是小型固定二进制样例，目的是跑通文件字节校验分支，不具备安装、签名或上传价值。为了避免把模拟字节误当生产产物，演示程序的输入根目录命名为fixtures/，输出报告始终带fixtureMode=true。发布团队在真实仓库中应把这一模式与生产模式分开，并给生产模式增加来源约束：只接受CI归档目录内存在且版本锁定的回执，不接收用户临时选中的任意sidecar文件。

三、先比较目标身份，再看摘要

本例的项目有两个逻辑部分。tools/release-gate.mjs是Node.js命令行检查器；ReleaseGatePage和ReleaseAuditPage只是文章配图所用的ArkUI演示页面，展示读取到的固定结果，没有触发真实设备上的Node进程。这个划分非常重要：Node.js脚本在开发机或CI环境执行，HarmonyOS模拟界面只展示报告，不能把两者合成一个“系统提供的Node.js发布API”。

首段代码实现最小身份核验。expected.bundleName来自发布计划，receipt.bundleName来自构建阶段可信回执，而不是从文件名或图标反推。releaseTag是团队自定义的交接标识，不是本文声称的官方versionCode字段，避免把内部标记等同于商店展示版本。

import { readFile } from 'node:fs/promises';

const expected = {
  taskId: 'REL-1010-19',
  bundleName: 'com.example.weeklyboard',
  releaseTag: '1.8.4'
};

export async function readReceipt(file) {
  const receipt = JSON.parse(await readFile(file, 'utf8'));
  if (receipt.taskId !== expected.taskId) {
    return { ok: false, reason: 'TASK_MISMATCH' };
  }
  if (receipt.bundleName !== expected.bundleName) {
    return { ok: false, reason: 'BUNDLE_MISMATCH' };
  }
  if (receipt.releaseTag !== expected.releaseTag) {
    return { ok: false, reason: 'RELEASE_TAG_MISMATCH' };
  }
  return { ok: true, receipt };
}

先返回身份差异并不是说“身份比哈希重要”。这是为了让诊断原因更加稳定：P03已经有明确的错误包名，无需继续宣称它的摘要状态是可信的发布资格；P04身份一致，才进入字节摘要核验。在审计报告里仍可以选择对所有已存在文件计算哈希用于取证，但最终是否放行必须要求身份与摘要都通过，不能执行一个失败后尝试另外的成功分支来覆盖失败。

对真实回执，还需要校验相对路径是否越过归档根目录。不能允许sidecar把路径写成../../secrets，然后让脚本到工作区之外读取文件。生产工具还应规范化路径、检查符号链接、拒绝目录而非普通文件，并尽可能通过只读归档获取输入。本文代码为了突出“包名回执”和“文件哈希”两层差异，未给出完整的受限路径解析器，不能直接以这段节选处理不可信外部输入。

四、摘要校验关注的是确切字节，不是截图

SHA-256是标准密码学摘要算法，Node.js可通过node:crypto计算。小型夹具可以一次readFile再createHash(...).update(...)；面对真正体积较大的APP包，应采用流式读入，避免把整份安装包长期保存在一个Node.js进程的堆内存中。下面使用异步迭代流处理字节，输出64位十六进制摘要。它仍只是文件内容摘要计算，不是签名证书链验证。

import { createReadStream } from 'node:fs';
import { createHash } from 'node:crypto';

export async function sha256File(path) {
  const hash = createHash('sha256');
  for await (const chunk of createReadStream(path)) {
    hash.update(chunk);
  }
  return hash.digest('hex');
}

export async function verifyBytes(path, receipt) {
  const actual = await sha256File(path);
  if (actual !== String(receipt.sha256).toLowerCase()) {
    return { ok: false, reason: 'HASH_MISMATCH', actual };
  }
  return { ok: true, reason: 'PASS', actual };
}

这段代码的错误路径不能省略。文件可能不存在、无读权限、在读取期间被另一个进程替换，也可能回执的摘要不是64位十六进制字符串。在正式流水线里需要先校验摘要格式，读之前确认是普通文件，失败后保留错误分类，并在只读或原子快照的输入目录上执行。若文件在检查后、上传前又被覆盖，刚才的哈希结果就不能证明最终上传的是同一组字节；所以更稳妥的交接是把通过校验的产物拷到内容寻址或不可变归档位置，再由下一个步骤取用。

为什么不给P04一个自动“覆盖为正确哈希”的选项？因为HASH_MISMATCH可能意味着回执过期，也可能意味着文件已经被改写。直接拿当前文件计算的新摘要覆盖期望值，会把验证行为变成修改证据。合理的动作是阻断、重新触发可信构建或要求发布责任人追查来源，而不是让用户点击“修复”就自动把差异抹平。

五、四个候选的不同结果应被解释清楚

固定样例清单如下。P01=phone-release.app，P02=tablet-release.app，它们的回执身份与计算摘要一致，在本地门禁中标为PASS。P03=preview-release.app，回执包名是com.example.weeklyboard.debug，不等于发布计划里的com.example.weeklyboard，标为BUNDLE_MISMATCH。P04=hotfix-release.app，包名一致但当前文件摘要与受信回执中的期望摘要不同，标为HASH_MISMATCH。

所谓PASS只是说这两份模拟字节与sidecar约定一致。不能在这里写“发布包已通过华为检测”，更不能说“可以直接上架”。未来即使它们是真实APP产物，还要通过签名检查、包结构校验、AGC上传和平台审核等独立步骤。主页面展示RELEASE_HOLD是批次级状态：只要交接清单内仍有必须阻断的候选，就不建议把整批包装成“已就绪”。

主界面里四个候选有两个绿标和两个红标，批次总数、通过数、阻断数对应4/2/2。其中原因计数是bundleMismatch=1和hashMismatch=1，它们既是两个独立候选，也是两个不同排障方向。某些实际工程可能同一个候选同时存在多个错误。那时如果既统计“阻断包数”又统计“问题条目数”，两者可以不同，报告字段必须明确；本轮的1+1=2只是这组固定输入恰好成立。

阅读页面时还应注意时间的意义。2026-10-10 12:28:15是样例检查完成时刻，不是AGC上传时间，不是打包时间的证明，更不是某次审核结果发布时间。页面上的文件大小、平台类型等可视属性同样属于样例描述，只有脚本实际读取并保存在报告中的字段才能用作本地校验依据。对无法从可信来源得到的字段，界面应该显示“未知”，而不是根据文件名猜测设备类型。

六、诊断表不应隐藏最关键的失败路径

ReleaseAuditPage把P03和P04排在最后，是为了让接手的人先看到两种不一致：包名多了.debug，以及摘要内容变化。P03的修复方向通常是回到构建变体配置与应用身份来源查错，确认它是否本来就是预览用途；P04则要定位文件在构建、复制、上传等待队列中的哪个环节发生变化。两者都不应该靠手工改写诊断文案来“绿化”结果。

本例的日志按四个阶段设计：12:28:11加载本地sidecar，12:28:12完成候选身份核对，12:28:13完成模拟摘要分支，12:28:14汇总两通过两阻断，12:28:15输出RELEASE_HOLD。这些顺序只是固定夹具的业务事件顺序，不是一次真实构建的秒级耗时。正式工具应记录UTC时间、CI作业ID、输入目录快照标识、Node版本和工具自身版本，以便两次执行报告可以对照。

差异详情页故意说明“这不是签名验证”。SHA-256是否相等和证书签名是否有效没有直接的逻辑等价关系。错误地把HASH_MISMATCH写成“签名错误”，会让排障者跑去处理证书或权限，反而遗漏归档字节被替换的真正线索。后续增加签名检查时应提供独立字段，例如signatureCheck: PASS/FAIL/NOT_RUN，并在问题明细中展示独立来源和验证工具版本。

七、把结果码做成有顺序的状态机

主流程的优先级是：任务身份核验→应用包名与内部标识校验→文件存在性与安全路径检查→字节摘要计算→候选准入汇总。任何一步抛出异常，都不能默认变成通过。尤其在CI脚本中，catch后打印一条warning但仍退出状态码0，会让自动化系统误把失败当作合格；门禁型工具应该让阻断状态显式反映在退出码上。

下面给出汇总逻辑的核心段落。candidates应来自经过结构验证的清单，checkOne负责执行前两段代码及输入路径检查。因为本文关注的是设计边界，展示的是函数调用关系而非一个可以脱离工程目录单独运行的完整CLI。

export async function runGate(candidates, checkOne) {
  const rows = [];
  for (const item of candidates) {
    try {
      rows.push(await checkOne(item));
    } catch (error) {
      rows.push({ id: item.id, status: 'BLOCKED',
        reason: 'IO_OR_FORMAT_ERROR' });
    }
  }
  const accepted = rows.filter(r => r.status === 'PASS').length;
  const blocked = rows.length - accepted;
  const state = blocked === 0 ? 'RELEASE_READY' : 'RELEASE_HOLD';
  return { total: rows.length, accepted, blocked, state, rows,
    agcUpload: 'NOT_RUN', appParse: 'NOT_RUN', signatureVerify: 'NOT_RUN' };
}

// CLI入口需在拿到报告后显式设置退出码：
// process.exitCode = report.blocked === 0 ? 0 : 2;

这里故意不在错误分支构造PASS，也没有使用Promise.all对大量文件并发读取。并发摘要很容易抢占磁盘带宽，遇到几十个真实安装包时应限制同时打开的文件数量。文件流结束后底层句柄通常由流关闭流程回收；异常路径也需要确保资源清理与可诊断错误。输出报告写盘宜采用临时文件写完再原子替换，避免控制台进程在写到一半时中断，留下一个看起来存在却不可解析的“合格清单”。

八、验收先看“不该放行”的分支

第一个反例是包名错位：给P03写入.debug包名，即使它的文件内容摘要与其回执匹配，也必须返回BUNDLE_MISMATCH。这一点确保身份检验不会被哈希结果短路。第二个反例是回执过期：保持P04的包名一致，但用另一份固定字节覆盖文件，预期返回HASH_MISMATCH，不能自动将新摘要回填覆盖原凭据。第三个反例是文件丢失：删除候选源文件后，预期错误状态而不是空文件摘要或自动忽略该候选。

第四个反例是路径逃逸：如果sidecar指定父目录或符号链接跳到工作区外，应在触碰目标文件之前阻断。这一条不在本文核心代码节选里直接实现，但必须列入真正交付前的安全清单。第五个反例是二次执行：同一份不可变归档重复核验，应得到相同的候选状态。若首次通过、第二次失败，说明中间有输入变化或环境不稳定，不能把它解释成AGC自动更新了审核结论。

第六个用例检验批次阻断：四个候选里两个通过、两个失败，最终必须仍是RELEASE_HOLD；不能以“通过率50%”给出建议提交。这里不讨论真实发布流程是否允许按设备或国家拆包，那由产品发布策略和官方平台规则确定。在一个自定义的“同批交接清单”里，任何被标记为必选的候选存在阻断，就应该阻止整批交接，避免后续有人从文件夹里随意挑一个看起来绿色的包。

九、实际发布链路还欠哪些证据

到这里，最容易产生的误判是：既然P01、P02都通过SHA-256，为什么还不能点击上传？原因并不神秘。本文使用的只是模拟产物和构建侧回执，不具备APP解析结果，没有验证应用签名、Profile或证书，也没有连接AGC账号。工具界面里AGC_UPLOAD、APP_PARSE和SIGNATURE_VERIFY都写着NOT_RUN，这就是操作边界。

真正落地时，应先用当前DevEco Studio编译出真实产物，按照团队可信CI流程生成sidecar，使用官方工具核实实际APP身份与签名，再关联到AGC项目和上传流程。每个阶段都应生成自己的报告，记录执行人或作业ID，以及输入产物摘要。后一个阶段可以引用前一个阶段的哈希作为关联键，但不能复用前一个阶段的“通过”结果代替自己的验证。

还有一个小取舍：对正在等待签名或平台校验的包，先不在页面上显示“可发布”，而显示“可进入下一道校验”。这样听起来不那么有成就感，却能明显减少团队把本地预检当成审核结果的机会。RELEASE_READY在本模型里也只代表本地回执全部一致，不是APP审核通过；本文这组样例最终没有进入这个状态。

从协作角度再补一个安全边界：CI作业生成的sidecar不应该允许发布值班人员直接编辑。需要更换包时，重新选择可信构建任务并重新产出回执；需要补交材料时，给材料单独建立修订记录。把两种操作混在一个可编辑表单里，看似省去一次重跑，实际上是把证据来源交给了最容易在赶进度时出错的手工环节。本文的两种阻断原因都应指向对应构建作业，而不是只展示一个红色感叹号。

十、资料来源与适用边界

本文以华为2026-05-19更新的《端侧应用配置》中AppScope/app.json5的bundleName关联要求，以及华为2025-11-05更新的《选择待发布的安装包》平台操作说明作为官方依据：

https://developer.huawei.com/consumer/cn/doc/doccenter-capabilities/payment-config-app-identity-info

https://developer.huawei.com/consumer/fr/doc/app/agc-help-release-app-choose-pkg-0000002278981434

本例的releaseTag、ReleaseReceiptGate、RELEASE_HOLD、sidecar格式与错误码均为业务工具自行定义，不属于华为官方发布接口或审核结论。Node.js的流读取与createHash来自稳定的运行时标准模块，真正部署时仍需锁定Node版本、审查第三方依赖并保存脚本版本。此轮没有生成真实安装包，没有做APP内部解析，也没有登录AGC。我们能确定的是给定四条演示回执的分类应为两个通过、两个阻断，并能够准确说清阻断发生在哪一层。