鸿蒙PC生态的脚步声越来越近这两年身边做三方软件移植的朋友明显变多。大家最常遇到的问题不是代码适配而是辛辛苦苦把Electron、Tauri甚至Flutter应用编译成ohos-sdk产物之后卡在“签名”这一关。用ohos-sdk生成的库或二进制如果不做正确的自动签名要么装不上要么运行时被系统拦截之前所有的移植工作全部白费。这篇文章我就把鸿蒙PC生态下三方软件移植中ohos-sdk产物自动签名的完整实现思路、脚本细节和避坑经验一次说清楚。文章面向的读者很明确正在做鸿蒙PC版应用适配、想把Linux/Windows软件迁到鸿蒙PC体系里、或者准备搭CI自动构建流水线的开发者。无论你是从Electron/Tauri这类跨平台框架进来还是自己用NDK编译了原生库只要能产出hap格式的安装包这套自动签名方案都能直接落地。1. 三方移植为什么绕不开“签名”这道坎1.1 鸿蒙PC生态里三类移植路径最后都汇聚到同一个动作鸿蒙PC版这两年开放力度很大三方软件移植主要有三条典型路径。第一条是源码级适配把跨平台框架的代码重新编译目标平台产物Electron应用移植鸿蒙教程里最常见的做法就是替换底层Node.js运行时、重新打包资源。第二条是二进制级移植对已经有Linux/macOS体系的闭源软件或老项目直接把.so动态库、可执行文件搬过来在鸿蒙的兼容层里运行。第三条是沙箱/容器方案在鸿蒙上起一个轻量虚拟机把未适配的二进制整个装进去跑。不管走哪条路在鸿蒙上能被用户正常安装、启动、申请权限的最终形态必须是一个签名合法的hap包。系统在安装时做的第一件事就是校验签名签名不合法直接拒绝安装。也就是说移植的代码工作做得再好签名这步没过产品就是零。我在给一个Tauri 2应用做鸿蒙适配时就踩过这个坑。当时代码编译、资源都没问题ohos-sdk生成的产物也正常但因为用的是临时自签名证书安装到真机上直接被拦截日志里一行“verify signature failed”看得人血压飙升。后来老老实实把签名流程做成自动化流水线这个问题才算根治。1.2 签名不是“穿个马甲”它在鸿蒙里的真实职责很多从Android开发过来的同事会以为签名就是给包做个标记、防篡改。鸿蒙的签名体系远比这个复杂它同时承担了三件关键事。第一件是完整性校验。hap包内所有文件都会被Hash处理并写入签名块安装时系统逐文件比对任何文件被改动过哪怕一个字节都会触发校验失败。这对移植场景尤其重要——因为迁移的.so库经常被后续热修复脚本替换一不小心就破坏了原始签名。第二件是来源可信。签名证书链必须能追溯到华为的根证书体系开发证书、发布证书、Profile描述文件组成一条完整的信任链。系统不会信任随便一个自签名证书这就解释了为什么很多“本地能装、换台设备就装不上”的情况本质是证书信任链断了。第三件是权限映射。hap里声明的受控权限比如访问网络、读取存储、调用设备能力必须由Profile里明确定义。你移植的软件如果某个权限没被Profile覆盖运行时就会静默拒绝表现出来就是功能异常但代码没报错。我见过不止一个案例明明逻辑没问题就是因为权限映射缺失用户数据读写失败排查半天才找到根因。理解这三层职责后你就会明白自动签名不能只是“把签名工具跑一遍”这么简单它必须保证证书正确、Profile准确、校验动作完整三个缺一不可。2. 自动签名方案设计与工具链组装2.1 手工签名流程到底有多痛来自一线的真实体验在没有自动化之前我手工签一个包走的是这条路线先用DevEco Studio打开工程在“File Project Structure Signing Configs”里勾选自动签名登录华为账号让IDE生成调试证书构建一次提取hap。听起来不复杂但实际做移植项目时这套流程根本扛不住。首先是构建频率问题。三方软件移植阶段几乎每天都在改代码Electron的asar资源包、动态库的每次更新都要产出新hap手工操作一次至少20分钟一天下来时间全耗在UI点击上。其次是证书管理混乱多个项目同时推进时每个项目的证书、Profile存放在不同目录密码还不一样光整理这些就够头疼。最致命的是证书过期——调试证书有效期短过期后DevEco Studio虽然会自动续期但如果你在同一台机器上同时维护多个模块IDE的自动续期偶尔会签错证书产出一个“看起来正常、实际装不上”的包。手工签名还有一个隐藏风险没有校验环节。IDE签名完直接给包但包的签名链是否完整、Profile是否匹配当前包IDE不会主动告诉你。等到真机安装失败再回头查白白浪费半天时间。2.2 自动签名管线的五个关键环节为了把手工流程彻底替代掉我设计的自动签名管线分成五个环节每个环节都有明确输入输出这样既方便调试也能嵌入CI。第一个是产物扫描。构建工具链输出物五花八门有unsigned的hap、有未打包的中间目录、有散落的.so和资源文件。管线需要统一扫描、筛选出所有需要签名的hap按项目名、版本号、构建时间整理好方便后面批量处理。第二个是证书管理。密钥库文件.p12、证书文件.cer、Profile文件.p7b集中存放密码不写在脚本里而是从环境变量或密钥管理系统读取。这一步非常关键因为脚本一旦写死密码证书泄露风险极高CI日志也会成为安全隐患。第三个是签名执行。核心是通过命令行调用ohos-sdk自带的hap-sign-tool.jar对每一个hap执行签名操作输出到指定目录。这个环节我会在下一章展开讲参数细节很容易出错。第四个是结果校验。签名完了不能直接归档要用hap-sign-tool.jar的verify-app命令反向校验确认签名链完整、Profile匹配、包体可被系统识别。这一步是手工流程里最容易被省略的但也是最能避免线上翻车的。第五个是失败告警。签名失败的包要单独归档错误日志格式化输出关键错误证书过期、Profile不匹配直接告警到团队群而不是让CI默默地失败。没有这一步你大概率会在第二天早上才发现昨晚构建的包全废了。2.3 工具选型为什么最终选择hap-sign-tool.jar为核心自动签名的工具链核心是ohos-sdk里的hap-sign-tool.jar它由OpenHarmony的developtools项目维护是官方提供、多平台支持、可直接命令行调用的签名验签工具。我对比过几条路用DevEco Studio的GUI适合单次操作不适合批量应该自动化用Web端AGC平台的签名服务适合发布版证书管理但不适合本地开发高频构建直接写代码调用签名SDK虽然灵活但维护成本高没有官方工具的稳定性。hap-sign-tool.jar的优势在于它把复杂的签名逻辑封装成命令行参数——输入密钥库、证书、Profile、待签名文件输出签名后的文件逻辑透明、结果可预期。而且它同时支持sign-app签名hap和verify-app校验签名这两条命令基本能满足本地构建和CI集成的所有需求。工具链其余部分我用Python 3做编排配合标准库的subprocess、glob、logging不引入第三方依赖。这样无论是开发机还是CI容器只要装了Python就能跑省去了依赖同步的麻烦。3. 实操ohos-sdk签名工具的自动化封装细节3.1 必须吃透的hap-sign-tool.jar关键参数先看一条最核心的签名命令这是整个自动化的地基java -jar hap-sign-tool.jar sign-app \ -mode local \ -keyAlias key0 \ -signAlg SHA256withECDSA \ -keystore debug.p12 \ -storePass $STOREPASS \ -keyPass $KEYPASS \ -certpath debug.cer \ -profile debug.p7b \ -inFile app_unsigned.hap \ -outFile app_signed.hap参数看起来多但逐个拆开其实逻辑很清晰。-mode指定签名模式local表示本地签名remote则走华为签名服务开发期用local就够了。-keyAlias没商量的余地必须和密钥库生成时设置的别名一致最常见的坑是大小写和特殊字符不匹配。-signAlg是签名算法目前支持SHA256withECDSA和SHA512withECDSA。选型时有个细节ECDSA算法对CPU要求低在大规模流水线构建时能明显节省时间所以我默认用SHA256withECDSA安全性也够。如果你的包对安全等级有硬指标再上SHA512withECDSA代价是签名计算和校验时间略有增加。-keystore是密钥库文件路径-storePass和-keyPass分别是密钥库密码和密钥别名密码。certpath是证书文件profile是描述文件两者都影响系统对应用的信任判定。inFile指定待签名包outFile指定输出路径。执行成功的标志是退出码为0且输出文件存在、体积和输入文件接近签名后通常增加几十KB。这里必须强调一点绝对不要把密码明文写进命令里。用环境变量引用或者用CI平台的secret管理这是自动签名方案的安全底线。3.2 Python脚本批量签名一份能直接抄作业的实现在实际项目中一次构建可能产出多个hap手动逐个签名效率太低。我为这个场景封装了一个Python签名脚本核心逻辑是扫描目录、批量调用hap-sign-tool.jar、记录每步日志。下面是关键代码框架import subprocess import logging import glob import os from pathlib import Path # 从环境变量读取敏感信息 HAP_SIGN_TOOL hap-sign-tool.jar KEYSTORE debug.p12 ALIAS key0 CERT debug.cer PROFILE debug.p7b def sign_hap(in_file, out_dir): out_file os.path.join(out_dir, Path(in_file).name) cmd [ java, -jar, HAP_SIGN_TOOL, sign-app, -mode, local, -keyAlias, ALIAS, -signAlg, SHA256withECDSA, -keystore, KEYSTORE, -storePass, os.environ[STORE_PASS], -keyPass, os.environ[KEY_PASS], -certpath, CERT, -profile, PROFILE, -inFile, in_file, -outFile, out_file, ] logging.info(signing %s - %s, in_file, out_file) result subprocess.run(cmd, capture_outputTrue, textTrue) if result.returncode ! 0: logging.error(sign %s failed: %s, in_file, result.stderr) return False return verify_hap(out_file) def verify_hap(hap_file): cmd [ java, -jar, HAP_SIGN_TOOL, verify-app, -inFile, hap_file, -outCertChain, hap_file .chain.cer, -outProfile, hap_file .p7b, ] result subprocess.run(cmd, capture_outputTrue, textTrue) return result.returncode 0 def batch_sign(src_dir, out_dir): os.makedirs(out_dir, exist_okTrue) success 0 for hap in glob.glob(os.path.join(src_dir, *.hap)): if sign_hap(hap, out_dir): success 1 logging.info(signed %d/%d haps, success, len(glob.glob(os.path.join(src_dir, *.hap))))脚本逻辑不复杂但有三个细节值得说。第一verify_hap的成功与否是整个批处理的核心判断依据。如果签名通过但校验失败这个包绝不能归档必须标记为失败。第二日志要打出inFile和outFile的对应关系这样排查问题时能快速定位到具体产物。第三每次批量签名前脚本会先检查密钥库、证书、Profile是否存在、是否过期避免跑到一半才发现文件缺失白跑一趟。如果你把移植产物同时包含.so库或ELF二进制并且这些库会被独立分发或加载那签名逻辑要再往前一步把这些库打包进hap后再签名。也就是说对库和二进制的签名是发生在批量构建阶段而不是对单个.so文件签名。这个理解可以避免你陷入“怎么给.so单独签名”的误区。3.3 把签名嵌进CI流水线GitLab CI落地实录单机跑通签名脚本只是第一步真正省心的是把签名嵌进CI流水线实现每次提交代码自动构建、自动签名、自动归档。我以GitLab CI为例把核心配置思路拆开讲。在.gitlab-ci.yml里签名步骤放在构建步骤之后、归档步骤之前大致是这样sign: stage: sign script: - python3 tools/sign_pipeline.py --src build_output --out signed_output artifacts: paths: - signed_output/*.hap only: - tags这里有个关键点CI环境里不落地敏感文件。密钥库文件、证书、Profile通过GitLab CI的secret变量注入脚本从环境变量读取密码而密钥库本身的托管有两种做法——一是用GitLab的secure files功能上传二是用s3等对象存储保存下载链接CI启动时临时拉取构建结束后删除。我比较推荐后者能做到证书文件不留存在CI机器上security团队审查也好交代。还有一个经验签名任务尽量用tags触发而不是每次commit都触发。因为三方软件移植阶段commit频率很高每次都做签名归档会把CI资源打满而tags通常是稳定版本签出来即等于可交付。这样既节省Pipeline时间也避免临时commit签出来的包被误当正式包使用。签名阶段的超时时间也要单独设置建议180秒以上。Electron应用移植鸿蒙后的hap通常有几百MB签名过程虽然快但大文件复制、校验都耗时默认的60秒超时很可能不够用。4. 签名失败排查实录与避坑清单4.1 五类高频签名错误速查表做自动签名半年多以来我把遇到的错误整理成了一张速查表照着查基本能解决大部分问题。错误现象根本原因解决方法verify-app报证书链不完整证书cer和密钥库不是同一套或证书过期重新生成密钥库和证书保持alias一致安装时“Install Failed: signature”hap被篡改过或者签名后做了二次打包确保签名是最后一步签名后不再改动hap高版本系统安装失败Profile中权限声明与本包不全一致在AGC平台上同步更新Profile对齐profile.p7b运行期报权限不足或请求错误Profile缺少对应受控权限映射检查Profile的permissions标签补全声明构建机器换个环境就失败keystore路径、JDK版本不一致锁定JDK版本并统一使用相对路径参考信息里有一条“android请求正常鸿蒙请求2300056”的热词这类运行期请求报错虽然不是签名本身的报错但我在排查类似案例时发现根因往往在签名环节的权限映射缺失——功能代码没问题权限被静默拦截最终体现成业务请求失败。所以如果你移植后遇到诡异的运行期失败第一反应不应该是查代码而是先把签名后的Profile权限全部列一遍。4.2 踩过几次坑才总结出的四个细节第一个坑是JDK版本。hap-sign-tool.jar对JDK版本有要求OpenJDK 8和OpenJDK 17的底层行为差异会导致签名结果在某些系统版本上不兼容。我现在统一用OpenJDK 11在所有开发机和CI容器里锁死版本才彻底解决“本地签的包能装、CI签的包不能装”的玄学问题。第二个坑是时间戳。签名时默认不带时间戳的话证书过期后包会失效。建议在签名命令里加上对时间戳服务器的支持这样即便证书在中途过期已经签好的包依然能正常安装。我早期漏掉这个配置结果半年后一批已交付的包全部无法安装只能重新签发教训惨痛。第三个坑是符号表较大导致的签名异常缓慢。来自NDK编译的.so文件如果未strip体积很大hap打包后签名计算耗时成倍增长。解决方案是在构建阶段统一strip产物。这个优化不复杂但对Pipeline整体时间影响很大。第四个坑是批量签名脚本并发问题。你是不是觉得用multiprocessing并行签名更快实际测试下来hap-sign-tool.jar并行执行时偶尔会互相干扰造成日志串写、产物混乱。我最终改成单进程顺序签名耗时多一点点但稳定性和排查便利性完全不是一个级别。4.3 自动化签名落地的最后一块拼图验收演练签名做完了还不算完最好定期做一次签名验收演练。具体做法是每月挑一个最新的签名产物用官方hdc工具安装到真机或模拟器上跑一遍核心功能链路确认安装、启动、权限申请、数据读写都正常。这个演练的价值在于它能提前发现证书链、Profile、系统版本兼容性这三者之间的隐性冲突——这些问题在纯命令行校验里很可能被漏掉。在我自己维护的移植项目里已经把“签名验收演练”设成每月固定任务产出一份完整的验收清单记录设备型号、系统版本、测试功能、签名信息、结论。三个月跑下来线上安装失败率从第一周的5%降到了0.3%左右效果相当显著。说回整体感受。鸿蒙PC生态留给三方软件的空间正在快速打开但签名的门槛也实实在在地存在。好在这个门槛一旦用自动化跨过去后续每次构建、每个版本发布都会变得非常顺畅。我个人的建议是如果你正在做相关移植别犹豫尽早把签名流水线搭起来。从最开始就用自动化的方式处理证书、签名、校验后面的版本迭代会让你轻松得多。
鸿蒙PC三方移植：ohos-sdk产物自动签名与CI集成实战
鸿蒙PC生态的脚步声越来越近这两年身边做三方软件移植的朋友明显变多。大家最常遇到的问题不是代码适配而是辛辛苦苦把Electron、Tauri甚至Flutter应用编译成ohos-sdk产物之后卡在“签名”这一关。用ohos-sdk生成的库或二进制如果不做正确的自动签名要么装不上要么运行时被系统拦截之前所有的移植工作全部白费。这篇文章我就把鸿蒙PC生态下三方软件移植中ohos-sdk产物自动签名的完整实现思路、脚本细节和避坑经验一次说清楚。文章面向的读者很明确正在做鸿蒙PC版应用适配、想把Linux/Windows软件迁到鸿蒙PC体系里、或者准备搭CI自动构建流水线的开发者。无论你是从Electron/Tauri这类跨平台框架进来还是自己用NDK编译了原生库只要能产出hap格式的安装包这套自动签名方案都能直接落地。1. 三方移植为什么绕不开“签名”这道坎1.1 鸿蒙PC生态里三类移植路径最后都汇聚到同一个动作鸿蒙PC版这两年开放力度很大三方软件移植主要有三条典型路径。第一条是源码级适配把跨平台框架的代码重新编译目标平台产物Electron应用移植鸿蒙教程里最常见的做法就是替换底层Node.js运行时、重新打包资源。第二条是二进制级移植对已经有Linux/macOS体系的闭源软件或老项目直接把.so动态库、可执行文件搬过来在鸿蒙的兼容层里运行。第三条是沙箱/容器方案在鸿蒙上起一个轻量虚拟机把未适配的二进制整个装进去跑。不管走哪条路在鸿蒙上能被用户正常安装、启动、申请权限的最终形态必须是一个签名合法的hap包。系统在安装时做的第一件事就是校验签名签名不合法直接拒绝安装。也就是说移植的代码工作做得再好签名这步没过产品就是零。我在给一个Tauri 2应用做鸿蒙适配时就踩过这个坑。当时代码编译、资源都没问题ohos-sdk生成的产物也正常但因为用的是临时自签名证书安装到真机上直接被拦截日志里一行“verify signature failed”看得人血压飙升。后来老老实实把签名流程做成自动化流水线这个问题才算根治。1.2 签名不是“穿个马甲”它在鸿蒙里的真实职责很多从Android开发过来的同事会以为签名就是给包做个标记、防篡改。鸿蒙的签名体系远比这个复杂它同时承担了三件关键事。第一件是完整性校验。hap包内所有文件都会被Hash处理并写入签名块安装时系统逐文件比对任何文件被改动过哪怕一个字节都会触发校验失败。这对移植场景尤其重要——因为迁移的.so库经常被后续热修复脚本替换一不小心就破坏了原始签名。第二件是来源可信。签名证书链必须能追溯到华为的根证书体系开发证书、发布证书、Profile描述文件组成一条完整的信任链。系统不会信任随便一个自签名证书这就解释了为什么很多“本地能装、换台设备就装不上”的情况本质是证书信任链断了。第三件是权限映射。hap里声明的受控权限比如访问网络、读取存储、调用设备能力必须由Profile里明确定义。你移植的软件如果某个权限没被Profile覆盖运行时就会静默拒绝表现出来就是功能异常但代码没报错。我见过不止一个案例明明逻辑没问题就是因为权限映射缺失用户数据读写失败排查半天才找到根因。理解这三层职责后你就会明白自动签名不能只是“把签名工具跑一遍”这么简单它必须保证证书正确、Profile准确、校验动作完整三个缺一不可。2. 自动签名方案设计与工具链组装2.1 手工签名流程到底有多痛来自一线的真实体验在没有自动化之前我手工签一个包走的是这条路线先用DevEco Studio打开工程在“File Project Structure Signing Configs”里勾选自动签名登录华为账号让IDE生成调试证书构建一次提取hap。听起来不复杂但实际做移植项目时这套流程根本扛不住。首先是构建频率问题。三方软件移植阶段几乎每天都在改代码Electron的asar资源包、动态库的每次更新都要产出新hap手工操作一次至少20分钟一天下来时间全耗在UI点击上。其次是证书管理混乱多个项目同时推进时每个项目的证书、Profile存放在不同目录密码还不一样光整理这些就够头疼。最致命的是证书过期——调试证书有效期短过期后DevEco Studio虽然会自动续期但如果你在同一台机器上同时维护多个模块IDE的自动续期偶尔会签错证书产出一个“看起来正常、实际装不上”的包。手工签名还有一个隐藏风险没有校验环节。IDE签名完直接给包但包的签名链是否完整、Profile是否匹配当前包IDE不会主动告诉你。等到真机安装失败再回头查白白浪费半天时间。2.2 自动签名管线的五个关键环节为了把手工流程彻底替代掉我设计的自动签名管线分成五个环节每个环节都有明确输入输出这样既方便调试也能嵌入CI。第一个是产物扫描。构建工具链输出物五花八门有unsigned的hap、有未打包的中间目录、有散落的.so和资源文件。管线需要统一扫描、筛选出所有需要签名的hap按项目名、版本号、构建时间整理好方便后面批量处理。第二个是证书管理。密钥库文件.p12、证书文件.cer、Profile文件.p7b集中存放密码不写在脚本里而是从环境变量或密钥管理系统读取。这一步非常关键因为脚本一旦写死密码证书泄露风险极高CI日志也会成为安全隐患。第三个是签名执行。核心是通过命令行调用ohos-sdk自带的hap-sign-tool.jar对每一个hap执行签名操作输出到指定目录。这个环节我会在下一章展开讲参数细节很容易出错。第四个是结果校验。签名完了不能直接归档要用hap-sign-tool.jar的verify-app命令反向校验确认签名链完整、Profile匹配、包体可被系统识别。这一步是手工流程里最容易被省略的但也是最能避免线上翻车的。第五个是失败告警。签名失败的包要单独归档错误日志格式化输出关键错误证书过期、Profile不匹配直接告警到团队群而不是让CI默默地失败。没有这一步你大概率会在第二天早上才发现昨晚构建的包全废了。2.3 工具选型为什么最终选择hap-sign-tool.jar为核心自动签名的工具链核心是ohos-sdk里的hap-sign-tool.jar它由OpenHarmony的developtools项目维护是官方提供、多平台支持、可直接命令行调用的签名验签工具。我对比过几条路用DevEco Studio的GUI适合单次操作不适合批量应该自动化用Web端AGC平台的签名服务适合发布版证书管理但不适合本地开发高频构建直接写代码调用签名SDK虽然灵活但维护成本高没有官方工具的稳定性。hap-sign-tool.jar的优势在于它把复杂的签名逻辑封装成命令行参数——输入密钥库、证书、Profile、待签名文件输出签名后的文件逻辑透明、结果可预期。而且它同时支持sign-app签名hap和verify-app校验签名这两条命令基本能满足本地构建和CI集成的所有需求。工具链其余部分我用Python 3做编排配合标准库的subprocess、glob、logging不引入第三方依赖。这样无论是开发机还是CI容器只要装了Python就能跑省去了依赖同步的麻烦。3. 实操ohos-sdk签名工具的自动化封装细节3.1 必须吃透的hap-sign-tool.jar关键参数先看一条最核心的签名命令这是整个自动化的地基java -jar hap-sign-tool.jar sign-app \ -mode local \ -keyAlias key0 \ -signAlg SHA256withECDSA \ -keystore debug.p12 \ -storePass $STOREPASS \ -keyPass $KEYPASS \ -certpath debug.cer \ -profile debug.p7b \ -inFile app_unsigned.hap \ -outFile app_signed.hap参数看起来多但逐个拆开其实逻辑很清晰。-mode指定签名模式local表示本地签名remote则走华为签名服务开发期用local就够了。-keyAlias没商量的余地必须和密钥库生成时设置的别名一致最常见的坑是大小写和特殊字符不匹配。-signAlg是签名算法目前支持SHA256withECDSA和SHA512withECDSA。选型时有个细节ECDSA算法对CPU要求低在大规模流水线构建时能明显节省时间所以我默认用SHA256withECDSA安全性也够。如果你的包对安全等级有硬指标再上SHA512withECDSA代价是签名计算和校验时间略有增加。-keystore是密钥库文件路径-storePass和-keyPass分别是密钥库密码和密钥别名密码。certpath是证书文件profile是描述文件两者都影响系统对应用的信任判定。inFile指定待签名包outFile指定输出路径。执行成功的标志是退出码为0且输出文件存在、体积和输入文件接近签名后通常增加几十KB。这里必须强调一点绝对不要把密码明文写进命令里。用环境变量引用或者用CI平台的secret管理这是自动签名方案的安全底线。3.2 Python脚本批量签名一份能直接抄作业的实现在实际项目中一次构建可能产出多个hap手动逐个签名效率太低。我为这个场景封装了一个Python签名脚本核心逻辑是扫描目录、批量调用hap-sign-tool.jar、记录每步日志。下面是关键代码框架import subprocess import logging import glob import os from pathlib import Path # 从环境变量读取敏感信息 HAP_SIGN_TOOL hap-sign-tool.jar KEYSTORE debug.p12 ALIAS key0 CERT debug.cer PROFILE debug.p7b def sign_hap(in_file, out_dir): out_file os.path.join(out_dir, Path(in_file).name) cmd [ java, -jar, HAP_SIGN_TOOL, sign-app, -mode, local, -keyAlias, ALIAS, -signAlg, SHA256withECDSA, -keystore, KEYSTORE, -storePass, os.environ[STORE_PASS], -keyPass, os.environ[KEY_PASS], -certpath, CERT, -profile, PROFILE, -inFile, in_file, -outFile, out_file, ] logging.info(signing %s - %s, in_file, out_file) result subprocess.run(cmd, capture_outputTrue, textTrue) if result.returncode ! 0: logging.error(sign %s failed: %s, in_file, result.stderr) return False return verify_hap(out_file) def verify_hap(hap_file): cmd [ java, -jar, HAP_SIGN_TOOL, verify-app, -inFile, hap_file, -outCertChain, hap_file .chain.cer, -outProfile, hap_file .p7b, ] result subprocess.run(cmd, capture_outputTrue, textTrue) return result.returncode 0 def batch_sign(src_dir, out_dir): os.makedirs(out_dir, exist_okTrue) success 0 for hap in glob.glob(os.path.join(src_dir, *.hap)): if sign_hap(hap, out_dir): success 1 logging.info(signed %d/%d haps, success, len(glob.glob(os.path.join(src_dir, *.hap))))脚本逻辑不复杂但有三个细节值得说。第一verify_hap的成功与否是整个批处理的核心判断依据。如果签名通过但校验失败这个包绝不能归档必须标记为失败。第二日志要打出inFile和outFile的对应关系这样排查问题时能快速定位到具体产物。第三每次批量签名前脚本会先检查密钥库、证书、Profile是否存在、是否过期避免跑到一半才发现文件缺失白跑一趟。如果你把移植产物同时包含.so库或ELF二进制并且这些库会被独立分发或加载那签名逻辑要再往前一步把这些库打包进hap后再签名。也就是说对库和二进制的签名是发生在批量构建阶段而不是对单个.so文件签名。这个理解可以避免你陷入“怎么给.so单独签名”的误区。3.3 把签名嵌进CI流水线GitLab CI落地实录单机跑通签名脚本只是第一步真正省心的是把签名嵌进CI流水线实现每次提交代码自动构建、自动签名、自动归档。我以GitLab CI为例把核心配置思路拆开讲。在.gitlab-ci.yml里签名步骤放在构建步骤之后、归档步骤之前大致是这样sign: stage: sign script: - python3 tools/sign_pipeline.py --src build_output --out signed_output artifacts: paths: - signed_output/*.hap only: - tags这里有个关键点CI环境里不落地敏感文件。密钥库文件、证书、Profile通过GitLab CI的secret变量注入脚本从环境变量读取密码而密钥库本身的托管有两种做法——一是用GitLab的secure files功能上传二是用s3等对象存储保存下载链接CI启动时临时拉取构建结束后删除。我比较推荐后者能做到证书文件不留存在CI机器上security团队审查也好交代。还有一个经验签名任务尽量用tags触发而不是每次commit都触发。因为三方软件移植阶段commit频率很高每次都做签名归档会把CI资源打满而tags通常是稳定版本签出来即等于可交付。这样既节省Pipeline时间也避免临时commit签出来的包被误当正式包使用。签名阶段的超时时间也要单独设置建议180秒以上。Electron应用移植鸿蒙后的hap通常有几百MB签名过程虽然快但大文件复制、校验都耗时默认的60秒超时很可能不够用。4. 签名失败排查实录与避坑清单4.1 五类高频签名错误速查表做自动签名半年多以来我把遇到的错误整理成了一张速查表照着查基本能解决大部分问题。错误现象根本原因解决方法verify-app报证书链不完整证书cer和密钥库不是同一套或证书过期重新生成密钥库和证书保持alias一致安装时“Install Failed: signature”hap被篡改过或者签名后做了二次打包确保签名是最后一步签名后不再改动hap高版本系统安装失败Profile中权限声明与本包不全一致在AGC平台上同步更新Profile对齐profile.p7b运行期报权限不足或请求错误Profile缺少对应受控权限映射检查Profile的permissions标签补全声明构建机器换个环境就失败keystore路径、JDK版本不一致锁定JDK版本并统一使用相对路径参考信息里有一条“android请求正常鸿蒙请求2300056”的热词这类运行期请求报错虽然不是签名本身的报错但我在排查类似案例时发现根因往往在签名环节的权限映射缺失——功能代码没问题权限被静默拦截最终体现成业务请求失败。所以如果你移植后遇到诡异的运行期失败第一反应不应该是查代码而是先把签名后的Profile权限全部列一遍。4.2 踩过几次坑才总结出的四个细节第一个坑是JDK版本。hap-sign-tool.jar对JDK版本有要求OpenJDK 8和OpenJDK 17的底层行为差异会导致签名结果在某些系统版本上不兼容。我现在统一用OpenJDK 11在所有开发机和CI容器里锁死版本才彻底解决“本地签的包能装、CI签的包不能装”的玄学问题。第二个坑是时间戳。签名时默认不带时间戳的话证书过期后包会失效。建议在签名命令里加上对时间戳服务器的支持这样即便证书在中途过期已经签好的包依然能正常安装。我早期漏掉这个配置结果半年后一批已交付的包全部无法安装只能重新签发教训惨痛。第三个坑是符号表较大导致的签名异常缓慢。来自NDK编译的.so文件如果未strip体积很大hap打包后签名计算耗时成倍增长。解决方案是在构建阶段统一strip产物。这个优化不复杂但对Pipeline整体时间影响很大。第四个坑是批量签名脚本并发问题。你是不是觉得用multiprocessing并行签名更快实际测试下来hap-sign-tool.jar并行执行时偶尔会互相干扰造成日志串写、产物混乱。我最终改成单进程顺序签名耗时多一点点但稳定性和排查便利性完全不是一个级别。4.3 自动化签名落地的最后一块拼图验收演练签名做完了还不算完最好定期做一次签名验收演练。具体做法是每月挑一个最新的签名产物用官方hdc工具安装到真机或模拟器上跑一遍核心功能链路确认安装、启动、权限申请、数据读写都正常。这个演练的价值在于它能提前发现证书链、Profile、系统版本兼容性这三者之间的隐性冲突——这些问题在纯命令行校验里很可能被漏掉。在我自己维护的移植项目里已经把“签名验收演练”设成每月固定任务产出一份完整的验收清单记录设备型号、系统版本、测试功能、签名信息、结论。三个月跑下来线上安装失败率从第一周的5%降到了0.3%左右效果相当显著。说回整体感受。鸿蒙PC生态留给三方软件的空间正在快速打开但签名的门槛也实实在在地存在。好在这个门槛一旦用自动化跨过去后续每次构建、每个版本发布都会变得非常顺畅。我个人的建议是如果你正在做相关移植别犹豫尽早把签名流水线搭起来。从最开始就用自动化的方式处理证书、签名、校验后面的版本迭代会让你轻松得多。
