鸿蒙 PC Markdown 编辑器构建交付：Debug、Release HAP 与哈希校验

程序员清洒

30人浏览 · 2026-07-25 23:10:27

程序员清洒 · 2026-07-25 23:10:27 发布

鸿蒙 PC Markdown 编辑器构建交付：Debug、Release HAP 与哈希校验

应用在 DevEco中能运行，不等于已经形成可重复交付。OhMarkdown同时包含 ArkTS原生代码和 Vite Web内核，构建顺序必须先生成离线 HTML，再由 Hvigor打入 HAP；Debug、Release、测试构建、签名状态、产物大小和哈希都要分别记录。

本文说明鸿蒙 PC项目的双构建链、API 24配置、单文件资源、Release unsigned HAP和 SHA-256校验。代码位于 https://gitcode.com/VON-/codex_md_oh，对应提交 3a9146e。

两套工具链组成一个产物

Web层：TypeScript、CodeMirror、markdown-it、DOMPurify和 CSS，经 Vite生成：

entry/src/main/resources/rawfile/editor/index.html

原生层：ArkTS、资源、module.json5和 rawfile，经 Hvigor生成 HAP。若只运行 assembleHap而没有先构建 Web，包里可能是旧 HTML；若只运行 Vite，得到的也不是鸿蒙应用。

构建脚本把顺序固化，避免依赖开发者记忆。

Web 构建输出到原生资源

export default defineConfig({
  base: './',
  plugins: [viteSingleFile()],
  build: {
    outDir:
      '../entry/src/main/resources/rawfile/editor',
    emptyOutDir: true,
    sourcemap: false,
    target: 'es2020',
    chunkSizeWarningLimit: 800
  }
});

base: './'让资源相对本地页面；singlefile把 JS/CSS内联，ArkWeb不需要外部文件或网络；emptyOutDir删除旧产物，避免废弃 chunk残留；Release不带 sourcemap减少包体和源码暴露。

构建目标 ES2020与当前 ArkWeb能力匹配，升级目标前需在 API 24设备验证。

build-editor 作为前置步骤

Debug与 Release脚本都先执行：

"$(dirname -- "$0")/build-editor.sh"

build-editor进入 web-editor并运行 npm build，TypeScript --noEmit先检查类型，再 Vite写 rawfile。任何失败因 set -eu中止，不会继续打包含旧资源的 HAP。

生产测试还读取最终 index.html，断言没有外部 script和 stylesheet。构建成功与离线约束同时进入门禁。

DevEco 环境显式配置

DEVECO_HOME="${DEVECO_HOME:-/Applications/DevEco-Studio.app/Contents}"

export JAVA_HOME="${JAVA_HOME:-$DEVECO_HOME/jbr/Contents/Home}"
export DEVECO_SDK_HOME="${DEVECO_SDK_HOME:-$DEVECO_HOME/sdk}"

默认使用 DevEco附带 JBR和 SDK，减少系统 Java差异；CI或其他机器可以覆盖。脚本不把个人 SDK路径写进仓库 local.properties。

构建日志要记录 DevEco、Hvigor和 SDK版本。仅记录“macOS”不足以复现工具链。

产品与 SDK 配置

{
  "name": "default",
  "signingConfig": "default",
  "targetSdkVersion": "6.1.1(24)",
  "compatibleSdkVersion": "6.1.1(24)",
  "runtimeOS": "HarmonyOS",
  "buildOption": {
    "strictMode": {
      "caseSensitiveCheck": true,
      "useNormalizedOHMUrl": true
    }
  }
}

目标和兼容均 API 24。严格大小写检查避免 macOS文件系统上可用、目标环境因路径大小写失败；规范 OHM URL减少模块引用差异。

buildModeSet明确 debug和 release。entry目标还包含 ohosTest，主模块和测试模块使用同一产品基线。

Debug 构建

exec "$DEVECO_HOME/tools/hvigor/bin/hvigorw" \
  assembleHap \
  --mode module \
  -p product=default \
  -p module=entry@default \
  -p buildMode=debug \
  --no-daemon

Debug用于快速安装模拟器、HDC调试和功能验证。exec让 Hvigor退出码成为脚本退出码，--no-daemon降低不同运行残留状态，代价是每次启动成本。

Debug通过证明 ArkTS、资源和 Web产物可以组装，不代表 Release优化路径通过。

Release 构建

Release只切换：

-p buildMode=release

entry release配置当前关闭 Ark混淆：

"arkOptions": {
  "obfuscation": {
    "ruleOptions": {
      "enable": false,
      "files": [
        "./obfuscation-rules.txt"
      ]
    }
  }
}

Alpha阶段优先调试与可诊断。正式发布前应启用并验证混淆，特别是 JavaScript Proxy方法名、反射资源和序列化字段不能被错误改名。

unsigned 不是发布包

根配置 signingConfigs为空，最终文件名为 entry-default-unsigned.hap。它可用于构建、体积和部分安装验证，但不能宣称完成商店签名与发布。

签名需要证书、profile、密钥保护和流水线密钥策略。不能把私钥提交仓库，也不能在文章中暴露本机证书路径。后续发布门禁应验证签名主体、有效期和权限。

产物大小与哈希

最终 Release unsigned HAP记录：

size: 1006605 bytes
sha256: 6d08d725bcb219ae97508281477cedb40d766d6860d7062e14d873f30322e31c

SHA-256把测试报告与具体二进制绑定。文件名可被覆盖，哈希能确认用户拿到的是同一产物。大小用于观察依赖和资源增长，不作为唯一优化目标。

每次正式基线应记录 commit、命令、环境、HAP相对路径、字节和哈希。重新构建若哈希不同，可能来自时间戳或非确定打包，需要区分可重复构建与内容一致。

UnitTestBuild

hvigorw UnitTestBuild \
  --mode module \
  -p product=default \
  -p module=entry@default \
  -p buildMode=test \
  -p unitTestMode=true \
  --no-daemon

该任务编译测试代码和依赖，捕获 ArkTS类型、Hypium引用和测试资源问题。它不代表设备执行4/4，报告必须单列。

测试模块声明2in1，让目标类型与 PC优先策略一致。未来 phone只是兼容，不应稀释 PC构建门禁。

构建产物安全检查

Web index不引用 CDN；ArkWeb关闭 file、online image、geolocation和 DOM storage；Release无 sourcemap。HAP还应进一步扫描：意外密钥、绝对路径、调试日志、测试 fixture、source map和未使用资源。

依赖许可证与 SBOM是做大后的必要交付项。package-lock和 oh-package-lock应进入版本管理，构建报告记录依赖版本。

鸿蒙 PC Release 版本

下图来自 MateBook Pro 2in1模拟器中的构建基线。ArkUI外壳和离线 Web编辑器来自同一 HAP构建链。

在这里插入图片描述

截图证明应用可运行，不证明签名和商店发布。HAP哈希、构建日志、自动化和设备行为共同形成交付证据。

包体增长管理

单 HTML包含 CodeMirror、markdown-it、DOMPurify和 CSS，是主要资源之一。新增插件前记录 HAP与 index.html差值。chunkSizeWarningLimit只是构建警告阈值，不是产品预算。

可建立预算：Web资源、HAP总大小、冷启动时间和内存共同评估。为了减几十 KB删除安全净化库是错误优化；先分析 source map、重复依赖和未用语言包。

可重复构建

真正可重复需要固定 Node、npm、DevEco、SDK、Hvigor、系统环境与 lockfile。当前脚本固定路径和依赖锁，但尚未证明两次构建字节哈希完全一致。HAP元数据可能含时间。

可先比较解包后业务文件哈希，确认内容一致；再研究打包时间戳归一。不要在没有验证时宣称 reproducible build。

交付前门禁

Release候选至少需要：Web 20/20、ohosTest 4/4、Debug/Release/UnitTestBuild成功、diff检查、模拟器主链、HAP大小与哈希、安全扫描、签名验证和 Alpha退出条件。当前签名、远程 CI和内部试用未完成，所以仍是工程基线而非正式发布。

当前边界

无发布签名；混淆关闭；原生构建只在本机 macOS；未生成 SBOM；未验证字节级可重复构建；没有自动上传产物和发布渠道。API 24之外兼容矩阵尚未建立。

产物回溯规则

每个准备交付的 HAP应配套一个本地清单，记录 Git提交、工作区是否干净、Web lockfile哈希、oh-package lockfile哈希、DevEco版本、SDK版本、构建模式、文件字节和 SHA-256。若工作区存在未提交代码，产物不能只绑定 HEAD，因为二进制可能包含无法从仓库重建的修改。

清单还应记录验证报告路径和模拟器目标，不把测试截图塞进 HAP。以后引入自动发布时，流水线从同一 commit生成清单和 artifact，下载页面显示哈希。用户反馈问题时先收集应用版本和构建 id，不要求用户上传文档。

Release目录中的旧 HAP应在新构建前清理或按 commit归档，避免人工拿错文件。文件名包含 product、module、mode仍不够区分两次构建，哈希才是最终身份。