一、我们要做什么1.1 发布需求表需求项详细说明签名体系搭建在华为 AGC 后台完成开发者实名认证申请发布证书与调试证书配置 .p12/.cer/.provision 三件套打包目标使用 DevEco Studio 构建生成带正式签名的 HAP 安装包支持多 ABI 架构arm64-v8a、x86_64发布渠道华为应用市场AppGallery Connect面向全球华为设备用户分发入口工程UniApp HBuilderX 导出的鸿蒙项目需与 DevEco Studio 版本兼容对接版本管理支持多版本并存、灰度发布、增量更新、回滚机制设备适配覆盖手机、平板、智慧屏、手表等多种鸿蒙设备形态1.2 预期效果完成本文流程后开发者将实现以下目标签名体系完备在 AGC 后台成功申请调试证书与发布证书.p12、.cer、.provision 文件配置正确签名验证通过。构建流程顺畅UniApp 导出鸿蒙工程后在 DevEco Studio 中一键构建生成带签名的 HAP 包无报错。上架成功HAP 包上传 AGC 应用市场通过审核后正式发布用户可在 AppGallery 搜索下载。多设备兼容同一签名配置覆盖手机、平板等多种设备类型无需重复申请。1.3 主要挑战证书链路复杂度高.p12私钥库、.cer公钥证书、.provision配置描述文件三者必须配套使用任意一个缺失或配置错误都会导致签名失败。初学者常混淆三者关系。AGC 申请流程繁琐企业开发者需完成营业执照认证、法人实名认证等多步骤个人开发者签名额度有限每年仅能申请有限数量的发布证书。UniApp 与 DevEco 版本匹配HBuilderX 导出的鸿蒙工程格式与 DevEco Studio 版本需严格对应版本不匹配可能导致构建失败或签名配置无法识别。多设备签名策略同一应用包名在不同设备类型手机/平板/智慧屏上可能需要差异化配置AGC 后台需分别创建对应的 Profile。CI/CD 集成难度自动化构建流程中如何安全传递签名密码、如何避免敏感信息泄露需要额外的工程化设计。二、数据模型设计为了规范化管理签名配置便于团队协作与自动化校验我们使用 TypeScript interface 定义证书与签名相关的数据模型。这些接口可作为配置生成脚本的基础类型约束。// src/models/signing-config.ts/** 签名类型枚举调试或发布 */exporttypeSigningTypedebug|release;/** 证书文件信息 */exportinterfaceCertInfo{/** 证书别名在 AGC 创建证书时自定义 */alias:string;/** .p12 私钥库文件相对路径 */p12Path:string;/** .p12 文件密码创建时设置不可找回 */p12Password:string;/** .cer 公钥证书文件相对路径 */cerPath:string;/** 证书指纹SHA256 格式AGC 后台可查询 */fingerprint?:string;/** 证书创建时间 */createdAt?:string;/** 证书过期时间 */expiresAt?:string;}/** Profile 配置描述文件信息 */exportinterfaceProvisionProfile{/** .provision 文件相对路径 */provisionPath:string;/** AGC 项目 ID */projectId:string;/** AGC 应用 ID字符串格式 */appId:string;/** Profile 类型调试或发布 */type:SigningType;/** Profile 过期时间 */expiresAt?:string;/** 允许的设备 UDID 列表调试签名用 */allowedDevices?:string[];}/** 完整签名配置 */exportinterfaceHarmonySigningConfig{/** 应用包名与 app.json5 中 bundleName 保持一致 */packageName:string;/** 签名类型 */signingType:SigningType;/** 证书信息 */cert:CertInfo;/** Profile 信息 */profile:ProvisionProfile;/** AGC 应用数字标识 */appIdentifier?:number;/** 支持的设备类型 */supportedDevices?:(phone|tablet|tv|wearable)[];/** 支持的 CPU 架构 */supportedAbis?:(arm64-v8a|x86_64|armeabi-v7a)[];}/** 构建产物元数据 */exportinterfaceBuildArtifact{/** 产物输出路径 */outputPath:string;/** HAP 包名称 */name:string;/** 是否已签名 */signed:boolean;/** 产物大小字节 */size:number;/** 签名算法 */signAlgorithm?:string;/** 构建时间戳 */buildAt:string;}/** AGC 发布配置 */exportinterfaceAGCReleaseConfig{/** AGC 项目 ID */projectId:string;/** AGC 应用 ID */appId:string;/** 版本号 */versionCode:number;/** 版本名称 */versionName:string;/** 更新日志多语言 */releaseNotes?:Recordstring,string;/** 发布范围全网或灰度 */releaseScope:full|gray;/** 灰度比例百分比 */grayPercentage?:number;}三、核心设计决策3.1 调试证书 vs 发布证书对比维度调试证书发布证书申请来源DevEco Studio 自动生成 或 AGC 自助申请仅 AGC 后台申请需实名认证有效期自动生成约 1 年AGC 申请可达 3 年通常 1–3 年可续期设备限制约 30 台测试设备需注册 UDID无设备数量限制应用市场❌ 无法用于上架✅ 上架唯一合法凭证签名验证宽松仅校验基础信息严格校验证书链与有效期适用阶段开发调试、功能验证、联调测试正式发布、版本更新选型建议开发阶段优先使用调试签名快速迭代验证正式上架前务必切换为发布签名切换操作仅需修改 build-profile.json5 中 signingConfigs 的路径引用。3.2 手动签名 vs 自动签名对比维度手动签名自动签名DevEco 内置配置复杂度较高需手动申请并配置三件套极低一键启用灵活性高完全可控可自定义签名算法低细节隐藏参数固定CI/CD 集成✅ 友好配置可脚本化❌ 不友好依赖 IDE 环境团队协作✅ 配置可提交 Git统一凭证❌ 依赖本地缓存难以共享安全性可控密码可环境变量注入依赖华为账号登录态适用场景企业项目、团队协作、自动化流水线个人开发、快速验证原型选型建议团队协作项目强烈推荐手动签名配置文件化程度高可纳入版本控制与 CI/CD 流水线个人快速验证原型可使用自动签名节省时间。3.3 AGC 签名 vs 本地调试签名对比维度AGC 签名本地调试签名文件来源AGC 后台下载标准格式DevEco 本地生成非标准格式跨设备使用✅ 统一凭证支持多设备❌ 绑定单设备应用市场兼容✅ 完全兼容❌ 无法上架多人协作✅ 凭证可共享❌ 各自生成不一致有效期管理AGC 后台可视化查看需手动记录选型建议正式发布统一使用 AGC 签名体系开发阶段可先用本地调试签名快速启动待上架前统一迁移至 AGC 签名。四、完整代码实现4.1 签名配置文件详解鸿蒙项目的签名配置位于项目根目录或 entry 模块目录下的 build-profile.json5 文件中。以下展示完整的签名配置结构。// entry/build-profile.json5 { apiType: stageMode, buildOption: { externalNativeOptions: { path: ./src/main/cpp/CMakeLists.txt, arguments: , cppFlags: , }, sourceOption: { group: { main: ./src/main, test: ./src/test, }, }, }, buildOptionSet: [ { name: release, arkOptions: { obfuscation: { ruleOptions: { enable: true, }, }, }, }, ], targets: [ { name: default, runtimeOS: HarmonyOS, }, ], products: [ { name: default, signingConfig: defaultSign, compileSdkVersion: 5, compatibleSdkVersion: 5, }, { name: release, signingConfig: releaseSign, compileSdkVersion: 5, compatibleSdkVersion: 5, }, ], }签名凭证配置节点// signingConfigs 配置通常在 app/build-profile.json5 或单独配置文件 { signingConfigs: { defaultSign: { storeFile: ./resources/base/media/debug.p12, storePassword: debug123, keyAlias: debugKey, keyPassword: debugKey123, signAlgorithm: SHA256withECDSA, profile: ./resources/base/media/debug.provision, certpath: ./resources/base/media/debug.cer, }, releaseSign: { storeFile: ./resources/base/media/release.p12, storePassword: YOUR_RELEASE_P12_PASSWORD, keyAlias: releaseKey, keyPassword: YOUR_RELEASE_KEY_PASSWORD, signAlgorithm: SHA256withECDSA, profile: ./resources/base/media/release.provision, certpath: ./resources/base/media/release.cer, }, }, }4.2 应用基础配置app.json5 定义应用全局属性需与 AGC 后台创建的应用信息保持一致。// entry/src/main/module.json5 { module: { name: entry, type: entry, description: $string:module_desc, mainElement: EntryAbility, deviceTypes: [ phone, tablet, 2in1, ], deliveryWithInstall: true, installationFree: false, pages: $profile:main_pages, abilities: [ { name: EntryAbility, srcEntry: ./ets/entryability/EntryAbility.ets, description: $string:EntryAbility_desc, icon: $media:layered_image, label: $string:EntryAbility_label, startWindowIcon: $media:startIcon, startWindowBackground: $color:start_window_background, exported: true, skills: [ { entities: [entity.system.home], actions: [action.system.home], }, ], }, ], }, }// app.json5应用级配置 { app: { bundleName: com.atomgit.demoapp, vendor: atomgit, versionCode: 1000000, versionName: 1.0.0, icon: $media:app_icon, label: $string:app_name, }, }4.3 Hvigor 构建命令详解Hvigor 是鸿蒙官方构建工具基于 TypeScript 实现支持增量编译与并行构建。# 查看可用任务hvigor--help# 清理构建产物hvigor clean# 构建 default product调试签名hvigor assembleHap--productdefault# 构建 release product发布签名hvigor assembleHap--productrelease# 构建所有 producthvigor assembleHap--productall# 启用增量编译加速hvigor assembleHap--productrelease --no-daemon# 指定模块构建hvigor :entry:assembleHap--productrelease# 分析构建依赖hvigor assembleHap--analyzenormal--productrelease# 输出路径说明# 调试包entry/build/default/outputs/default/entry-default-signed.hap# 发布包entry/build/release/outputs/release/entry-release-signed.hap4.4 签名配置注入脚本以下 Node.js 脚本用于在 CI/CD 环境中动态注入签名密码避免将敏感信息硬编码在配置文件中。// scripts/inject-signing.jsconstfsrequire(fs);constpathrequire(path);/** * 从环境变量读取签名配置并注入 build-profile.json5 * 环境变量P12_PASSWORD, KEY_ALIAS, KEY_PASSWORD */functioninjectSigningConfig(){constconfigPathpath.resolve(__dirname,../entry/build-profile.json5);letcontentfs.readFileSync(configPath,utf-8);constp12Passwordprocess.env.P12_PASSWORD;constkeyAliasprocess.env.KEY_ALIAS||releaseKey;constkeyPasswordprocess.env.KEY_PASSWORD;if(!p12Password||!keyPassword){console.error(❌ 缺少必要的环境变量P12_PASSWORD 或 KEY_PASSWORD);process.exit(1);}// 替换占位符contentcontent.replace(/YOUR_RELEASE_P12_PASSWORD/g,p12Password).replace(/YOUR_RELEASE_KEY_PASSWORD/g,keyPassword).replace(/keyAlias:\s*releaseKey/,keyAlias: ${keyAlias});fs.writeFileSync(configPath,content,utf-8);console.log(✅ 签名配置注入成功);}injectSigningConfig();4.5 UniApp 导出鸿蒙工程对接流程步骤一HBuilderX 导出鸿蒙项目在 HBuilderX 中打开 UniApp 项目右键点击项目根目录 → 发行 → 原生 App-云打包 → 选择 HarmonyOS 平台 → 导出鸿蒙工程。步骤二导入 DevEco Studio打开 DevEco Studio → File → Open → 选择导出目录中的 entry 文件夹 → 等待项目索引完成。步骤三配置签名方式一自动签名File → Project Structure → Signing Configs → 勾选 “Automatically generate signature” → 登录华为开发者账号 → 自动生成调试签名。方式二手动签名将 AGC 下载的 .p12、.cer、.provision 文件放置到 entry/src/main/resources/base/media/ 目录修改 build-profile.json5 中 signingConfigs 配置指向这些文件。步骤四同步 bundleName登录 AGC 后台 → 我的应用 → 创建应用 → 获取 App ID 和 bundleName。在导出项目的 app.json5 中将 bundleName 修改为 AGC 后台显示的包名确保完全一致。步骤五构建验证执行hvigor assembleHap --product default验证签名配置正确无报错后切换到 release product 进行正式构建。五、深度技术原理5.1 数字签名原理鸿蒙应用的签名机制基于 PKI公钥基础设施体系采用 ECDSA椭圆曲线数字签名算法结合 SHA-256 摘要算法确保应用的完整性与来源可信。签名流程摘要计算构建工具首先对 HAP 包内的所有文件计算 SHA-256 摘要生成唯一的消息摘要值。私钥签名使用开发者持有的私钥存储在 .p12 文件中对消息摘要进行 ECDSA 签名生成数字签名值。签名写入将签名值写入 HAP 包内的 META-INF/SIGNATURE1 文件同时生成 CERT.SF 记录各文件摘要。验证流程摘要重算系统安装 HAP 时重新计算包内文件的 SHA-256 摘要。公钥验证从 .cer 证书中提取公钥验证 SIGNATURE1 中的签名值是否与摘要匹配。证书链校验验证 .cer 证书是否由可信 CA华为中间证书签发证书链是否完整。Profile 校验解析 .provision 文件检查证书指纹是否在允许列表中应用权限声明是否合法。5.2 证书链结构鸿蒙签名体系采用标准的三层证书链架构华为根证书Huawei Root CA └── 华为中间证书Huawei Intermediate CA └── 开发者证书Developer Certificate, .cer各层职责根证书预置在鸿蒙系统中作为信任锚点不可更改。中间证书由华为运维用于签发开发者证书可定期轮换。开发者证书包含开发者公钥与应用信息由开发者在 AGC 申请。开发者在 AGC 申请的 .cer 文件实际包含开发者公钥与中间证书的合并体系统验证时自动完成证书链追溯。5.3 HAP 包结构详解HAPHarmonyOS Ability Package是鸿蒙应用的标准分发格式实际为 ZIP 压缩包。app-release.hap/ ├── META-INF/ │ ├── CERT.SF # 各文件摘要列表 │ └── SIGNATURE1 # 数字签名块二进制 ├── assets/ │ └── entry/resources/ # 前端资源文件 ├── libs/ │ ├── arm64-v8a/ # ARM64 动态库 │ └── x86_64/ # x86_64 动态库 ├── resources/ │ ├── base/ │ │ ├── element/ # 字符串、颜色等资源 │ │ ├── media/ # 图片、图标 │ │ └── profile/ # 配置文件 │ └── rawfile/ # 原始资源 ├── module.json5 # 模块配置清单 └── pack.info # 包元信息关键文件说明SIGNATURE1存储 ECDSA 签名值安装时由系统验证。module.json5声明模块的能力Ability、权限、设备类型等元数据。libs/按 ABI 架构分目录存储原生动态库支持多架构共存。5.4 HAR 与 HAP 的区别HARHarmonyOS Archive静态共享库编译时被 HAP 引用并打包进 HAP不独立安装。HAPHarmonyOS Ability Package可独立安装的应用包包含 Ability 入口与完整资源。App Pack.app 格式多 HAP 的集合包用于一次上传多模块应用到 AGC由应用市场按设备类型分发。六、常见问题解答FAQQ1调试签名可以上架华为应用市场吗答不可以。调试签名生成的 HAP 包无法通过 AGC 审核系统的签名校验。华为应用市场仅接受使用 AGC 后台申请的正式发布证书签名的应用包。调试签名仅适用于开发阶段真机调试、内部测试分发。Q2.p12 密码忘记了怎么办答.p12 文件密码由开发者创建时自行设定华为服务端不存储该密码。一旦遗忘无法恢复。唯一解决方案是在 AGC 后台删除原证书重新申请新的发布证书下载新的 .p12 文件并更新项目中的签名配置。注意更换证书后已上架应用需重新签名并按新版本发布。Q3同一包名在不同设备类型上签名是否冲突答不冲突。同一 .p12 和 .provision 文件可覆盖手机、平板、智慧屏等多种设备类型。关键是在 AGC 后台创建应用时正确勾选支持的设备类型确保 Profile 包含所有目标设备的声明。build-profile.json5 中无需按设备拆分 products 配置。Q4UniApp 导出后报错 “code: 13500101bundle type not exist”答该错误通常由 app.json5 中的 bundleName 与 AGC 后台创建的应用包名不一致导致。解决步骤登录 AGC → 我的应用 → 选择目标应用 → 查看 App 信息 → 复制 bundleName → 在导出项目的 app.json5 中同步修改。此外检查 App IDappidentifier是否正确填入配置。Q5Profile 文件过期后如何更新答登录 AGC 后台 → 用户与访问 → 证书管理 → 找到对应 Profile → 点击重新生成或下载最新的 .provision 文件。替换项目中的旧文件后重新执行 hvigor 构建即可。Profile 过期不影响已发布的应用版本仅影响后续构建签名。Q6如何在 CI/CD 流水线中安全处理签名密码答推荐方案是将签名密码存储在 CI 系统的加密环境变量中如 GitHub Actions Secrets、GitLab CI Variables在构建前通过 Node.js 脚本动态注入到 build-profile.json5。切勿将含真实密码的配置文件提交到 Git 仓库。示例脚本见本文 4.4 节。七、运行效果UniApp 鸿蒙应用签名打包与上架全流程演示八、扩展方向CI/CD 流水线深度集成基于 GitHub Actions 或 Gitee Go 搭建自动化构建发布流水线实现代码提交后自动签名、构建、上传 AGC减少人工操作。多渠道包管理利用 product 配置生成不同签名的渠道包如企业内部分发包、应用市场公开包适配差异化分发场景。App Bundle 打包策略将多 HAP 合并为 .app 格式上传由 AGC 按设备特征自动下发最优包减少用户下载体积。增量更新与热修复探索鸿蒙 OTA 差分包机制与动态加载能力实现小版本快速修复无需全量更新。HarmonyOS NEXT 适配关注 API 5 新增签名特性与权限动态申请机制提前布局纯血鸿蒙生态。