打包签名鸿蒙PC实战:同一份源码,assembleHap 只出 HAP,assembleApp 多出来那几步在签什么

我一直以为「打包」就是把商城塞进一个 HAP 签个名,直到要出一份能提交应用市场的 .app,才发现 assembleHap 和 assembleApp 根本不是同一个模式下的两条命令:一个跑 33 个 module 级任务、止步于 SignHap,另一个跑 42 个任务、先签 HAP 再把 HAP 装进 .app 又签一次;这篇文章用真实构建日志和四件签名材料,把「两条命令差在哪」「.cer/.p12/.p7b 到底谁管什么」「为什么我打出了 .app 却仍然上不了架」这三个问题一次讲透。

仓库地址:/storage/Users/currentUser/Documents/DevEcoStudioProjects/tauri-hello(本系列实战工程);写作参考框架为 ohos-window-desktop-article 模板 A;构建工具 hvigorw.js(hmos-clt 自带),签名材料在 /storage/Users/currentUser/.ohos/config/,本文所有命令、任务名、字节数、有效期均来自本机真实构建日志与产物解包,不虚构上架流程。

0. 环境与实测设备

这一篇跟前面调系统 API、写业务页面都不一样,几乎不碰 ArkTS 代码,全程在跟 hvigor 命令、配置文件和二进制产物打交道。所以环境表里我把「SDK 路径」和「签名材料路径」都列全——这两样只要有一个不对,命令连第一行都跑不过去。

项版本 / 型号
DevEco Studio与本系列一致,API 26(HarmonyOS 6.0.0 SDK)
鸿蒙 SDKDEVECO_SDK_HOME=/storage/Users/currentUser/WorkBuddy/2026-11-21-17-24-54/harmony-sdk-home
构建工具node /data/service/hnp/hmos-clt.org/hmos-clt_1.0.0/hvigor/bin/hvigorw.js
hvigor 插件根 appTasks / entry hapTasks(@ohos/hvigor-ohos-plugin)
modelVersion5.0.5(根 oh-package.json5)
SDK 版本targetSdkVersion / compatibleSdkVersion 26.0.0,runtimeOS HarmonyOS
签名算法SHA256withECDSA,keyAlias debugKey
bundleNamecom.example.myapplication(AppScope/app.json5)
版本versionCode 1000000 / versionName 1.0.0
主验证命令--mode module assembleHap 33 tasks / --mode project assembleApp 42 tasks
降级验证--no-daemon 单条独立跑 + --stop-daemon 清理 daemon
产物entry-default-signed.hap、tauri-hello-default-signed.app
实测设备2in1(pack.info 里 deviceType 含 2in1),调试 profile 绑定 4 个 device-id

要说清楚一件事:这篇里的「上架」是命令与产物层面的,不是真的提交到了应用市场。 本工程用的是 type: debug 的调试 profile、开发证书、4 个设备白名单,.app 能打出来,但只能装到绑定的调试设备,提交市场要换 release profile 和发布证书。我把这条边界放在最前面,是不想让「BUILD SUCCESSFUL + 产出了 .app」被误读成「发行就绪」——这正是第 1 节要推翻的那个朴素理解。

1. 问题是怎么找上我的:我以为打个 release 包就能上架

商城功能、窗口能力、系统能力、业务页面都做完之后,剩下的活看起来最没有悬念:打包,上架。我一开始也以为就是把 build-profile.json5 里的 buildModeSet 从 debug 切到 release,跑一条命令,拿一个包,传上去。

结果第一条命令就给了我一个不太对劲的信号。我按之前的习惯跑:

cd /storage/Users/currentUser/Documents/DevEcoStudioProjects/tauri-hello
export DEVECO_SDK_HOME=/storage/Users/currentUser/WorkBuddy/2026-11-21-17-24-54/harmony-sdk-home
node /data/service/hnp/hmos-clt.org/hmos-clt_1.0.0/hvigor/bin/hvigorw.js --mode project -p product=default assembleApp --no-daemon

BUILD SUCCESSFUL in 14 s 607 ms,33 个任务,产物是 entry-default-signed.hap。我去 entry/build/default/outputs/default/ 一翻,确实有 HAP,但翻遍整个工程也没找到 .app。我一度以为是 -p product=default 写错了,或者 buildModeSet 没切过去,反复改配置重跑,HAP 照出,.app 照没有。

请添加图片描述

# 第一版:反复只出 HAP 的产物目录
entry/build/default/outputs/default/
├── entry-default-signed.hap      854714 B
├── entry-default-unsigned.hap    825707 B
└── pack.info                        578 B

请添加图片描述

后来把命令换成 --mode project assembleApp,日志里一下多出来一整段从没见过的 project 级任务,build/outputs/default/ 里才出现 tauri-hello-default-signed.app。把两份日志并排看,问题清楚了:assembleHap 是 module 级任务,它把 entry 模块打成一个 HAP 就收工;assembleApp 是 project 级任务,它先复用 HAP,再把所有模块的 HAP 连同 pack.info / pac.json 装进一个 .app 容器,然后对这个容器再签一次名。 少的是「装进容器再签」这一整层,不是某个配置开关没打开。

所以这个题目的边界,我用一句话钉死:「出 HAP」和「出可上架的 .app」是两条不同模式、不同任务链、两次签名的命令,配置里那七件签名材料贯穿始终;理解 .app 的容器结构和 profile 的 debug/release 差异,比记住一条命令重要。

拆开来是三件事:

  • 把两条命令各自的任务链、产物路径、字节数从真实日志里扒出来,讲清层次差异;
  • 把 .cer / .p12 / .p7b / .csr 四件材料与 build-profile.json5 的七个字段一一对上;
  • 把 p7b 解出真实内容,说清为什么当前 .app 能打、能装调试机,却上不了市场。

下面是干完之后的完整记录,包括我踩的每一个坑。

2. 效果展示

按老规矩,先给效果再讲原理。这一篇的「效果」不是界面,是命令输出和产物解包结果——两条命令跑出来的东西摆在一起看,差异比讲十分钟都直观。

请添加图片描述

这行状态不是装饰。左边 assembleHap 的产物目录只到 HAP + entry 级 pack.info(578 B);右边 assembleApp 在 build/outputs/default/ 下多出 tauri-hello-default-signed.app(651469 B)、tauri-hello-default-unsigned.app(636526 B)和 pac.json(36 B)。任务数 33 → 42,多出来的那一截就是打包容器和二次签名。日志里 BUILD SUCCESSFUL in 17 s 138 ms / 42 tasks 对应的是 --mode project 那条,不是把同一条命令跑快了。

第二张是 .app 解包。它本质是个 zip,里面只有三个文件:entry-default.hap(635280 B)、pack.info(832 B)、pac.json(36 B)。注意这里的 pack.info 是 83请添加图片描述
2 B,跟 HAP 目录里那个 578 B 的不是同一个文件——一个描述模块,一个描述整个 app 包。pac.json 内容就一行 {"dataProcess":[],"specialAPIs":[]}。pack.info 里 bundleType: app、deviceType: ["phone","tablet","2in1"]、apiVersion: {compatible:26, target:26, releaseType:"Release"},这些字段决定了这个包能被哪些设备、哪个 API 级别的市场接收。

请添加图片描述

第三张是把 .p7b 当 ASN.1 DER 解出来的内嵌 JSON。type: "debug"、issuer: "app_gallery"、validity 换算成 2026-11-22 01:19:28 UTC ~ 2027-11-22 01:19:28 UTC(整整一年)、debug-info.device-ids 是 4 个十六进制串、acls.allowed-acls 是空数组、permissions 是空对象。development-certificate 里是一整段 PEM 证书。这张图就是「为什么上不了架」的全部证据:调试 profile 把应用锁死在 4 台设备和开发证书上,市场不认这个。

主动交代边界:这三张图对应的产物字节是「2026-11-22 一次完整构建的实测快照」,签名产物带时间戳,同样源码重复构建会浮动几字节(signed HAP 实测在 854711 ~ 854714 之间跳)。所以图里的数字是那次构建的定值,不是实时读数;assembleApp 会把 HAP 覆盖成 release 签名版,两次命令的产物字节也确实不同。

3. 原理:从一份源码到两个包,中间到底有几层

要把这两条命令讲清,得先把「打包」这个词拆成四层,我用一张表归纳每层由哪个任务负责、产出什么、由谁签名。

层触发任务产物签名动作应用要回答什么
编译层CompileArkTS / BuildJS / CompileResourcemodules.abc、资源索引无ArkTS 严格模式下能不能编过
模块打包层PackageHap → PackingCheckentry-default-unsigned.hap无module.json / 权限 / 资源齐不齐
HAP 签名层SignHapentry-default-signed.hap第 1 次签名(签 HAP)用 .p12 私钥 + .p7b profile 签
App 打包层MakeProjectPackInfo → PackageApp*-unsigned.app无把 HAP 装进容器 + 写 pack.info
App 签名层SignPackagesFromApp → SignApp*-signed.app第 2 次签名(签 APP)对容器整体再签一次
汇总assembleHap / assembleApp——命令入口,本身只跑 1 ms

这里最重要的模型判断是:HAP 是「模块」,APP 是「应用包容器」;签名不是一次,是 HAP 一次、APP 一次,两次都用同一套七件材料,但作用对象不同。

assembleHap 走的是前三层,止步于 SignHap;assembleApp 把前三层全跑完(日志里能看到 SignHap),再补上后三层。这也是为什么 assembleApp 的任务数是 42 而不是 33——多的那 9 个里,日志明确能看到 7 个 :: 开头的 project 级任务:MakeProjectPackInfo、ProcessProjectPrivacyProfile、GeneratePackRes、PackageApp、SignPackagesFromApp、SignApp、assembleApp。

# 首次 assembleApp 成功日志(oOg6bV,节选,真实输出)
> hvigor Finished :entry:default@PackageHap... after 115 ms
> hvigor Finished :entry:default@PackingCheck... after 13 ms
> hvigor Finished :entry:default@SignHap... after 901 ms
> hvigor Finished :entry:assembleHap... after 1 ms
> hvigor Finished ::MakeProjectPackInfo... after 7 ms
> hvigor Finished ::ProcessProjectPrivacyProfile... after 7 ms
> hvigor Finished ::GeneratePackRes... after 2 ms
> hvigor Finished ::PackageApp... after 354 ms
> hvigor Finished ::SignPackagesFromApp... after 2 ms
> hvigor Finished ::SignApp... after 539 ms
> hvigor Finished ::assembleApp... after 1 ms
> hvigor BUILD SUCCESSFUL in 18 s 538 ms
42 tasks in total: 31 executed, 11 up-to-date

SignHap ... after 901 ms 和 SignApp ... after 539 ms 两行挨着,是「两次签名」最直接的证据;assembleHap ... after 1 ms 和 assembleApp ... after 1 ms 说明这两个入口任务本身只是个汇总钩子,真正的活在前面那些 :entry:default@ 和 :: 任务里。还有一个细节决定了后面所有排查方向:根 hvigorfile.ts 挂的是 appTasks,entry 的挂的是 hapTasks——--mode project 才有资格跑 appTasks 提供的 project 级任务,--mode module 根本看不到 PackageApp 这一层。

4. 工程怎么搭:七件材料、一个配置、两条命令

这一步是把「能打包」变成「讲得清打包」的转折。整个签名体系就落在一个配置文件和一组材料上,目录摊开是:

tauri-hello/
├── build-profile.json5              # 【核心】signingConfigs / products / buildModeSet
├── hvigorfile.ts                    # 根:appTasks(project 级任务来源)
├── oh-package.json5                 # modelVersion 5.0.5
├── AppScope/
│   └── app.json5                    # bundleName / versionCode / versionName
├── entry/
│   ├── hvigorfile.ts                # entry:hapTasks(module 级任务来源)
│   ├── build-profile.json5          # obfuscation(release 下 enable: false)
│   └── src/main/module.json5        # 4 项权限、abilities、deviceTypes
└── /storage/Users/currentUser/.ohos/config/
    ├── default_tauri-hello9Sp...E.cer   2914 B   # 证书(公钥)
    ├── default_tauri-hello9Sp...E.p12   1003 B   # 密钥库(私钥)
    ├── default_tauri-hello9Sp...E.p7b   4283 B   # 签名 profile
    └── default_tauri-hello9Sp...E.csr    456 B   # 证书请求(申请阶段用,打包不直接引用)

build-profile.json5 的 signingConfigs[0].material 是七个字段,四件材料里真正被命令引用的是三件(.cer / .p12 / .p7b),.csr 是当初向证书服务申请时用的,留在目录里但不在打包配置里:

// build-profile.json5 - signingConfigs[0](真实内容,节选)
{
  "name": "default",
  "material": {
    "storePassword": "00000020...F7B581F87B00FC9568F500D49D7",   // .p12 库密码(密文)
    "certpath": "/storage/.../default_tauri-hello9Sp...E.cer",   // 证书
    "keyAlias": "debugKey",                                        // 私钥别名
    "keyPassword": "00000020...F7B581F87B00FC9568F500D49D7",     // 私钥密码(密文)
    "profile": "/storage/.../default_tauri-hello9Sp...E.p7b",    // 签名 profile
    "signAlg": "SHA256withECDSA",                                  // 签名算法
    "storeFile": "/storage/.../default_tauri-hello9Sp...E.p12"    // 密钥库
  },
  "type": "HarmonyOS"
}

七个字段各有明确职责:storeFile 指向装私钥的 .p12,storePassword 开这个库,keyAlias 指定用哪把私钥,keyPassword 解这把私钥,certpath 是配对的证书(验签用),profile 是 .p7b(规定这个包能装哪、能用什么权限、有效期到哪天),signAlg 定算法。products[0] 里 targetSdkVersion / compatibleSdkVersion: "26.0.0"、runtimeOS: "HarmonyOS",signingConfig: "default" 把上面这套材料绑到 default 产品上;buildModeSet 列了 debug 和 release 两个构建模式——注意这里只是「模式名」,真正决定能不能上架的是 .p7b 里的 type,不是这个模式名,坑 7 会展开。

两条命令,最小可复现形式:

# 公共前置:SDK 路径必须显式给,否则 00303217
export DEVECO_SDK_HOME=/storage/Users/currentUser/WorkBuddy/2026-11-21-17-24-54/harmony-sdk-home
H="node /data/service/hnp/hmos-clt.org/hmos-clt_1.0.0/hvigor/bin/hvigorw.js"

# 命令一:module 级,出可安装的 HAP(调试用)
$H --mode module -p product=default assembleHap --no-daemon

# 命令二:project 级,出可提交的 APP 容器(上架用)
$H --mode project -p product=default assembleApp --no-daemon

--mode module / --mode project 是这一对命令最关键的差异,不是可省的装饰;-p product=default 选中 products[0] 从而选中 signingConfigs[0];--no-daemon 让每次构建起独立进程,避开 daemon 残留(坑 3)。

这里有一个容易被忽略的窗口期:两条命令都把 HAP 写到同一个 entry/build/default/outputs/default/ 路径,后者会覆盖前者。 我第一次把两条命令串在一条 shell 里连跑,assembleApp 结束时 HAP 已经是 release 签名版了,跟 assembleHap 那一刻量到的字节数对不上。要精确对比两种模式的产物,必须各自单独跑、各在命令结束那一刻立即读字节;否则「debug HAP 854714 B」这个数会被后一条命令悄悄改掉。这也是上一篇文章里把静态产物数字钉成「一次实测快照」的原因。

5. 把代码讲透

5.1 签名材料:四件东西、七个字段,谁管什么

接收侧最容易搞混的是「这么多文件到底哪个是哪个」。build-profile.json5 的 material 是把四件材料组织起来的那张表:

// build-profile.json5 - material 与四件材料的对应(真实路径,节选)
{
  "certpath": ".../default_tauri-hello9Sp1dATzCvWfDikbsvCOlNcxcEVoE8hymEdepxIMI8E.cer",
  "storeFile": ".../default_tauri-hello9Sp1dATzCvWfDikbsvCOlNcxcEVoE8hymEdepxIMI8E.p12",
  "profile":   ".../default_tauri-hello9Sp1dATzCvWfDikbsvCOlNcxcEVoE8hymEdepxIMI8E.p7b",
  // .csr 456 B 不在此配置中,仅用于证书申请阶段
  "signAlg": "SHA256withECDSA", "keyAlias": "debugKey"
}

三个细节值得单独说。第一,四个文件前缀完全一致(default_tauri-hello9Sp...E),因为它们是同一次「自动生成签名」批次产出的,bundleName 换了、前缀就换——目录里那一堆 MyApplication / harmony / ohos_hap 前缀的材料是别的项目批次留下的,跟本工程无关,别拿错。第二,.cer 2914 B 是证书(含公钥),.p12 1003 B 是 PKCS#12 密钥库(含私钥),两者配对;打包时 certpath 用于验签链、storeFile 用于取私钥签名。第三,.p7b 4283 B 不是证书,是「 provisioning profile 」——它规定这个包能被哪些设备装、能申请哪些权限、有效期到哪天,SignHap 和 SignApp 两次都读它。

反直觉陷阱:.p7b 里其实嵌着一份 JSON,不能直接当文本打开。 它是 ASN.1 DER 编码的 PKCS#7 结构,我用括号匹配从 latin-1 解码后的字符串里抠出完整 JSON(第 2 节那张图就是这么来的)。想直接 cat 看会是一堆乱码,得按 DER 解析或找可读字符串区间。降级上,如果拿到的 .p7b 是 release 版,type 会是 release、debug-info.device-ids 消失、bundle-info 换成发布证书——本工程当前不是,所以只能装调试机。

5.2 p7b profile:有效期、设备白名单、空 ACL 各自意味着什么

场景句:解出 JSON 不难,难的是读懂每个字段在「能不能上架」这件事上的分量。

// .p7b 内嵌 profile JSON(真实解出,节选,长串已截断)
{
  "version-name": "2.0.0",
  "version-code": 2,
  "uuid": "b2a07e40-b0be-488c-a2e5-c703028c4c65",
  "validity": { "not-before": 1795310368, "not-after": 1826846368 },
  "type": "debug",
  "bundle-info": {
    "developer-id": "30086000724875543",
    "development-certificate": "-----BEGIN CERTIFICATE-----\nMIICxTCCAkugAwIBAgIOCf1Q..."
  },
  "baseapp-info": {},
  "permissions": {},
  "debug-info": {
    "device-ids": ["454D5504D4143041524D...", "06FD93941430B5C9E8...",
                   "454D55057494E05838...", "56A40470079B2197AC..."]
  },
  "acls": { "allowed-acls": [] },
  "issuer": "app_gallery"
}

三个细节值得单独说。第一,validity 是两个 Unix 秒级时间戳,1795310368 → 2026-11-22 01:19:28 UTC、1826846368 → 2027-11-22 01:19:28 UTC,正好一年;调试证书一年到期,过期后连调试机都装不上,这是会真实卡到人的时间点。第二,debug-info.device-ids 四个串就是「只能装这 4 台」的白名单,type: debug + development-certificate(开发证书)共同把包锁在调试链路里。第三,acls.allowed-acls: [] 和 permissions: {} 是空的——本系列前面「审核失败」那篇讲过,声明了高风险权限但 profile 不给 ACL 就会装不上;这里反过来,四项权限都是 normal 级能拿到的(INTERNET / GET_NETWORK_INFO / READ_CALENDAR / WRITE_CALENDAR),所以空 ACL 不影响当前这个包。

反直觉陷阱:issuer: "app_gallery" 不等于「已经能上应用市场」。 它只说明这份 profile 由应用市场的证书服务签发,真正的「能上架」还需要 type: release、发布证书、以及没有 device-id 白名单。降级上,如果读者手上是 release profile,这段 JSON 里 debug-info 整块会消失、证书换成发布证书,permissions 可能带上申请到的 ACL 列表——判断能不能提交,看 type 和 device-ids 这两处最省事。

5.3 两条命令的任务链:33 与 42 之间那几步

场景句:光看产物名字分不清层次,把 build.log 里的任务名抽出来才看得清。

# module 级 assembleHap:build.log 里抽到的 32 个 entry:default@ 任务(真实,节选)
entry:default@PreBuild / MergeProfile / CreateBuildProfile / GeneratePkgContextInfo
entry:default@ProcessProfile / ProcessResource / CompileResource / CompileArkTS
entry:default@GeneratePkgModuleJson / ProcessCompiledResources
entry:default@PackageHap / PackingCheck / SignHap / CollectDebugSymbol
entry:default@GenerateMetadata / GenerateLoaderJson / CreateModuleInfo ...

# project 级 assembleApp:在上面之后追加的 :: 任务(真实)
::MakeProjectPackInfo / ::ProcessProjectPrivacyProfile / ::GeneratePackRes
::PackageApp / ::SignPackagesFromApp / ::SignApp / ::assembleApp

三个细节值得单独说。第一,PackageHap → PackingCheck → SignHap 是 HAP 的成型三连,两次命令都会跑;CollectDebugSymbol 只在带调试符号的构建里出现。ProcessProfile / MergeProfile 是把 module.json5 的权限、abilities 合进去的任务——前面「4 项权限」的收敛成果就是在这一步进包的。第二,:: 前缀是 project 级任务的标记,跟 :entry:default@ 的 module 级任务一眼可分;ProcessProjectPrivacyProfile 这个任务名也解释了为什么隐私配置文件会被收进 .app。第三,SignPackagesFromApp(2 ms)和 SignApp(539 ms)是两件事:前者大概率是准备「给 app 内所有包签名」的清单,后者是真正对容器整体写入签名块,所以 APP 的 signed/unsigned 差了 651469 − 636526 = 14943 B。

反直觉陷阱:任务数 42 不是「33 + 9 个全新任务」那么简单。 日志末尾写 31 executed, 11 up-to-date,说明 42 里有一部分是被增量缓存命中的;而且 --mode project 会把 module 级任务重新组织一遍,不是简单在末尾追加。降级上,如果只想验证「能不能编过」,--mode module assembleHap 足够;只有真要出 .app 时才上 --mode project assembleApp,多花的几秒是容器打包和二次签名的成本,不是浪费。

5.4 APP 容器内:pack.info、pac.json 和两个 pack.info 的区别

场景句:解包 .app 最容易踩的坑,是把它跟 HAP 目录里的 pack.info 当成同一个文件。

// build/outputs/default/ 与 .app 内 pack.info 对照(真实字节)
// ① entry 级:entry/build/default/outputs/default/pack.info   578 B
// ② app  级:tauri-hello-default-signed.app 内 pack.info      832 B(内容节选)
{
  "summary": {
    "app": { "bundleName": "com.example.myapplication",
             "bundleType": "app",
             "version": { "code": 1000000, "name": "1.0.0" } },
    "modules": [{
      "mainAbility": "EntryAbility",
      "deviceType": ["phone", "tablet", "2in1"],
      "abilities": [{ "name": "EntryAbility", "label": "$string:EntryAbility_label" }],
      "distro": { "moduleType": "entry", "installationFree": false,
                  "deliveryWithInstall": true, "moduleName": "entry" },
      "apiVersion": { "compatible": 26, "releaseType": "Release", "target": 26 }
    }]
  },
  "packages": [{ "deviceType": ["phone", "tablet", "2in1"],
                 "moduleType": "entry", "deliveryWithInstall": true,
                 "name": "entry-default" }]
}

三个细节值得单独说。第一,两个 pack.info 职责不同:578 B 那份在 HAP 产物目录里,描述 entry 模块;832 B 这份在 .app 容器内,描述整个应用包(summary.app + summary.modules + packages)。第二,releaseType: "Release" 是 API 级别的属性,不是说这个包是 release 签名——它跟 .p7b 的 type: debug 是两码事,别混。第三,deviceType: ["phone","tablet","2in1"] 说明这个 HAP 声明支持三类设备,本系列一直在 2in1(鸿蒙 PC)上验证;deliveryWithInstall: true 表示随应用安装一起分发。

pac.json 只有 36 B:{"dataProcess":[],"specialAPIs":[]},两个空数组。反直觉陷阱:空数组不是「缺内容」,是「这个包没有声明数据处理或特殊 API 用途」,属于合规申报字段。降级上,单模块工程(本例只有 entry)的 .app 里就是一个 HAP;如果工程拆了多个 feature 模块,容器里会出现多个 *-default.hap,packages 数组也会跟着变长,pack.info 的体积自然不止 832 B。

5.5 产物校验:怎么证明这个包真的签了、真的能装

场景句:BUILD SUCCESSFUL 是最没信息量的一行,真正的验证在解包之后。

# 校验 HAP 与 APP 内确实有签名和正确内容(本轮真实执行的 python 片段)
python3 - <<'PY'
import zipfile, json
z = zipfile.ZipFile('entry-default-signed.hap')
mj = json.loads(z.read('module.json'))
print('权限:', [p['name'] for p in mj['module']['requestPermissions']])
print('modules.abc 在包内:', 'ets/modules.abc' in z.namelist())
za = zipfile.ZipFile('tauri-hello-default-signed.app')
print('APP 内文件:', za.namelist())
PY

三个细节值得单独说。第一,module.json 里的 requestPermissions 必须是收敛后的 4 项,且没有 WRITE_MEDIA / WINDOW_TOPMOST / PRINT 残留——这是前面「审核失败」那篇修复成果的回归检查,每次重打包都要重验。第二,ets/modules.abc 是 ArkTS 编译产物,在包里才说明业务代码真编进去了;本轮还额外验了 perf.html / perf-bench.js 两个新文件在包内(上一篇文章的功能闭环)。第三,signed 与 unsigned 的字节差就是签名块:HAP 侧 854714 − 825707 = 29007 B,APP 侧 651469 − 636526 = 14943 B,两层签名各自往各自的对象里塞了签名数据。

反直觉陷阱:「有 *-signed.app 文件」不等于「签名有效」。文件名只是 hvigor 的命名约定,要确认签名块得看体积差和解包内容;要确保能装到目标设备,还得对上 .p7b 的 device-ids 和有效期。降级上,本工程当前对调试机可装、对应用市场不可提交——完整链路是:换 type: release 的 profile + 发布证书 → 重新配 signingConfigs → assembleApp → 走应用市场上传。这条链路的命令部分我验证了,材料替换部分属于账号与证书申请,不在本机可复现范围,我不假装跑过。

6. 我踩过的坑(每一条都有真实报错)

这一节可能是全文最值钱的部分。以下坑全部来自这次开发的真实报错和排查记录。

坑 1:DEVECO_SDK_HOME 没设对,命令第一行就跪。 现象:直接跑 hvigorw.js,报 SDK 无效。

> hvigor ERROR: 00303217 DEVECO_SDK_HOME is invalid
  (直接用系统默认 SDK 路径,里面没有 API 26 的完整工具链)

一开始以为是 hvigor 版本不对,后来才反应过来是 DEVECO_SDK_HOME 指到了一个不完整的目录。修法是显式导出本系列一直在用的那个路径:export DEVECO_SDK_HOME=/storage/Users/currentUser/WorkBuddy/2026-11-21-17-24-54/harmony-sdk-home。命令行构建不比 DevEco 图形界面,SDK 路径必须自己给全,别指望环境变量刚好对。

坑 2:SDK version 找不到,00303312 紧跟着来。 现象:换了个 SDK 目录后报版本缺失。

> hvigor ERROR: 00303312 SDK version not found / compatibleSdkVersion mismatch
  build-profile.json5 里写 26.0.0,SDK 目录里缺对应 version 描述

一开始以为是 compatibleSdkVersion 写法错("26.0.0" vs 26),后来才反应过来是 SDK 目录本身不完整,缺了 version 元数据。换回完整的 harmony-sdk-home 后,targetSdkVersion / compatibleSdkVersion: "26.0.0" 原样不动就过了。报错号指向配置,根因却可能在 SDK 目录,先确认目录完整性再改配置。

坑 3:daemon 残留,构建半途断连。 现象:连跑几次之后构建报 socket 错。

> hvigor Socket connect error: invalid payload
> hvigor Server has disconnected.

一开始以为是签名材料被占用,后来才反应过来是上一次的 hvigor daemon 进程状态脏了。修法是构建统一带 --no-daemon,必要时补一次 --stop-daemon 把残留进程清掉再跑。CI 或脚本里反复构建,--no-daemon 是省心的默认值;daemon 加速是给交互开发用的,不是给一次性命令用的。

坑 4:.hvigor/report 攒到 50 个,触发沙箱批量删除确认。 现象:把 assembleHap 和 assembleApp 串在一条命令里,第二条构建失败。

> hvigor ... assembleApp
  SAFE_DELETE 触发:.hvigor/report 累积到 50 个 json,批量删除需确认
  Server has disconnected.

一开始以为是签名冲突或产物覆盖,后来才反应过来是构建报告 JSON 攒太多,触发了沙箱的批量删除保护——纯缓存问题。修法是构建前把旧 report 清到只留最近 2 个,两条命令各自单独跑成功(14 s 607 ms / 33 tasks、17 s 138 ms / 42 tasks)。连续构建失败先查构建缓存和 daemon,别急着动签名配置。

坑 5:两条命令覆盖同一路径,量到的字节数对不上。 现象:明明 assembleHap 结束时量到 854714 B,跑完 assembleApp 再回头看,HAP 变成了 665676 B。

A) assembleHap → debug signed HAP 854714 B
B) assembleApp → 同一路径被 release 签名覆盖 → 665676 B

一开始以为是「优化把包压小了」,后来才反应过来两次构建把 HAP 写进了同一个 entry/build/default/outputs/default/,后者覆盖前者,且 release 不带调试符号本就更小。修法是把两种模式的数字定义成「各自构建完成那一刻的实测快照」,并在导出 JSON 里标上 staticSnapshot。同名产物被不同命令覆盖时,对比数据必须记录采样时刻,否则会得出「换个命令包就瘦了」的假结论。

坑 6:签名带时间戳,重复构建浮动几字节。 现象:同源码连跑两次 assembleHap,signed HAP 不一样。

构建 A:debug signed HAP 854711 B
构建 B:debug signed HAP 854714 B   ← 同样源码,差 3 B

一开始以为构建不确定、有隐藏输入,后来才反应过来签名块里带时间戳,每次签名自然不同。这不是 bug,是签名的正常性质;但它意味着任何「写死等于磁盘字节」的界面都会偶尔对不上。修法是把它明确定义成「一次实测快照」,把「哪次构建、多少 tasks、多少毫秒」一起写进数据。带时间戳的产物只能讲某次实测的快照,不能伪装成实时值;把采样上下文写进数据,数字就永远可溯源。

坑 7:buildModeSet 里的 release 没让我上架。 这是最隐蔽的一坑。现象:我把构建模式切成 release、assembleApp 也成功了,可把 .p7b 解出来一看,type 还是 debug。

// build-profile.json5 的 buildModeSet(真实)
"buildModeSet": [ { "name": "debug" }, { "name": "release" } ]
// .p7b 内嵌 profile(真实)
"type": "debug", "debug-info": { "device-ids": [ "...4 个..." ] }

一开始以为 buildModeSet 切到 release 就等于 release 签名,后来才反应过来二者完全无关:buildModeSet 是编译模式(影响优化、混淆、调试符号),type 是签名 profile 的类型(决定能装哪些设备、能不能进市场)。真上架要向应用市场申请 type: release 的 profile 和发布证书,替换 signingConfigs.material.profile 与 certpath。编译模式 ≠ 签名 profile 类型,一个管代码怎么编,一个管包能去哪,别被同名骗了。

坑 8:能打 .app ≠ 能发行。 这是工程化级别的一坑。三条命令我都跑通了、BUILD SUCCESSFUL 也拿了、.app 也解包验过结构了,但把 .p7b 的 type / device-ids / development-certificate 摆在一起看:

type: debug  +  4 个 device-ids  +  开发证书  +  有效期一年
→ .app 能打出来,只能装绑定调试设备,不能提交应用市场

一开始我差点在文章里写「打出了可上架的包」,后来把这条边界钉死:命令链路验证到位,材料替换属于账号权限,本机不可复现,如实标注。「BUILD SUCCESSFUL」「产出了 .app」「能装到任意设备」「能提交市场」是四件事,逐级收窄;把命令成功当成发行就绪,是最容易在最后一公里翻的车。

7. 现在怎么用:从一条命令到一份可复现的交付

两条命令不依赖额外安装,只要 DEVECO_SDK_HOME 指对、build-profile.json5 的七件材料齐全。接入与验证结果列在这里:

# 1) 出调试 HAP(module 级)
export DEVECO_SDK_HOME=/storage/Users/currentUser/WorkBuddy/2026-11-21-17-24-54/harmony-sdk-home
node hvigorw.js --mode module -p product=default assembleHap --no-daemon
# → BUILD SUCCESSFUL in 14 s 607 ms,33 tasks,entry-default-signed.hap

# 2) 出上架 APP(project 级,先清 report 再单独跑)
python3 -c "import glob,os;fs=sorted(glob.glob('.hvigor/report/*.json'),key=os.path.getmtime);[os.remove(f) for f in fs[:-2]]"
node hvigorw.js --mode project -p product=default assembleApp --no-daemon
# → BUILD SUCCESSFUL in 17 s 138 ms,42 tasks,tauri-hello-default-signed.app

# 3) 产物校验:解包看 module.json 权限、modules.abc、APP 内三文件
python3 -c "import zipfile;print(zipfile.ZipFile('build/outputs/default/tauri-hello-default-signed.app').namelist())"

测试数量交代:本轮两条命令各单独跑成功一次(assembleHap 33 tasks / assembleApp 42 tasks),HAP 与 APP 都做了 zip 解包校验——module.json 权限仍是 4 项、无 WRITE_MEDIA / WINDOW_TOPMOST / PRINT 残留、ets/modules.abc 在包内、APP 内 entry-default.hap + pack.info + pac.json 三文件齐全、perf.html / perf-bench.js 随包分发。签名材料七字段、p7b 九个关键字段、有效期换算、两个 pack.info 字节差,全部核对到本机真实文件。当前验证结果是「命令链路 + 产物结构」层面完整通过,「release profile 替换 + 应用市场提交」层面未在本机执行,如实标注。

免得读者踩到同一堵墙,硬限制清单:

  • 本工程 .p7b 是 type: debug 的调试 profile(4 个 device-ids + 开发证书 + 有效期一年),.app 能打出、能装绑定调试机,不能真的提交应用市场;上架要换 release profile 与发布证书。
  • buildModeSet 的 debug/release 是编译模式,与 .p7b 的 type 是签名 profile 类型,两件事,别混。
  • 两条命令都把 HAP 写到同一路径,后者覆盖前者;对比两种模式的产物必须各自单独构建、各在结束时刻读字节。
  • 签名产物带时间戳,重复构建浮动几字节属正常;本文所有静态字节是「2026-11-22 一次完整构建的实测快照」,不是实时读磁盘。
  • assembleApp 的 42 tasks 里含 11 up-to-date 增量命中,任务数会随缓存状态变,BUILD SUCCESSFUL 本身不证明签名有效。
  • .csr 只在证书申请阶段用,不在 signingConfigs.material 里;打包真正引用的是 .cer / .p12 / .p7b 三件。
  • 本文未覆盖账号侧操作:发布证书申请、profile 生成、应用市场上传与审核,这些不在本机可复现范围。

文档清单:配置 build-profile.json5(根 / AppScope/app.json5 / entry/build-profile.json5)、插件 hvigorfile.ts(根 appTasks / entry hapTasks)、签名材料 /storage/Users/currentUser/.ohos/config/、产物 entry/build/default/outputs/default/entry-default-signed.hap 与 build/outputs/default/tauri-hello-default-signed.app、真实日志 .hvigor/outputs/build-logs/build.log。

一开始我想的是「选个模式、跑条命令、拿个包」,把两条命令的任务链和四件签名材料摊开之后才明白:**打包真正的复杂度不在编译,而在「这个包被允许去哪里」——profile 的类型、设备白名单、有效期、两次签名的作用对象,共同决定了 BUILD SUCCESSFUL 之后它能不能真的被发行。

Logo

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

更多推荐