使用 DevEco Studio 配置 Flutter 鸿蒙签名

签名是鸿蒙应用从开发到发布绕不开的一环。本文以 E-Brufen 的真实签名为例,详解完整的证书配置流程。

一、为什么需要签名?

HarmonyOS 要求所有 HAP 包必须经过数字签名才能安装运行。签名体系包含四个关键文件:

文件 扩展名 用途
密钥库 .p12 存储开发者私钥和证书
证书 .cer 开发者的数字身份证明
Profile .p7b 应用发布配置文件(含权限和设备白名单)
签名请求 .csr 用于向 CA 申请证书

在 E-Brufen 项目根目录,你可以看到这四个文件:

复制代码
firstproject.p12     ← 密钥库
22.cer               ← 开发者证书
123456Release.p7b    ← 发布 Profile
firstproject.csr     ← 证书签名请求

二、生成签名材料

步骤 1:生成 CSR 和密钥库

在 DevEco Studio 中:

  1. Build → Generate Key and CSR
  2. 填写信息:别名(如 aaa)、密码、组织名称等
  3. 生成 .csr 和 .p12 文件

或者在命令行使用 keytool:

bash 复制代码
keytool -genkeypair -alias aaa -keyalg EC -sigalg SHA256withECDSA \
  -keystore firstproject.p12 -storetype PKCS12 -validity 3650

⚠️ E-Brufen 使用 SHA256withECDSA 算法------这是鸿蒙推荐的签名算法,兼顾安全性和性能。

步骤 2:申请证书

  1. 登录 AppGallery Connect
  2. 进入 证书管理 → 新增证书
  3. 上传刚才生成的 .csr 文件
  4. 下载颁发的 .cer 证书

    申请地址:https://developer.huawei.com/consumer/cn/service/josp/agc/index.html#

步骤 3:申请 Profile

  1. 在 AppGallery Connect 中进入 Profile 管理
  2. 创建新的 Profile,选择:
    • 证书(刚才申请的 .cer)
    • 设备类型(phone)
    • 应用包名:com.flutter.brufen
  3. 下载 .p7b Profile 文件

三、配置 build-profile.json5

将签名材料路径写入 ohos/build-profile.json5:

json5 复制代码
{
  "app": {
    "signingConfigs": [
      {
        "name": "default",
        "type": "HarmonyOS",
        "material": {
          "storeFile": "D:/Flutter/firstproject/firstproject.p12",
          "storePassword": "00000019314A5E64...",
          "keyAlias": "aaa",
          "keyPassword": "0000001994B09538...",
          "signAlg": "SHA256withECDSA",
          "profile": "D:/Flutter/firstproject/123456Release.p7b",
          "certpath": "D:/Flutter/firstproject/22.cer"
        }
      }
    ],
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compatibleSdkVersion": "6.1.0(23)",
        "runtimeOS": "HarmonyOS"
      }
    ]
  }
}

!在这里插入图片描述(https://i-blog.csdnimg.cn/direct/bdb522d8e1a84ee5b549920fb56391c5.png

🔒 安全提醒 :storePassword 和 keyPassword 是敏感信息。在生产项目中,应将签名文件路径和密码通过环境变量注入,而非硬编码在配置文件中。

四、配置 app.json5

确保 ohos/AppScope/app.json5 中的 bundleName 与 Profile 一致:

json5 复制代码
{
  "app": {
    "bundleName": "com.flutter.brufen",
    "vendor": "example",
    "versionCode": 1000000,
    "versionName": "1.0.0",
    "icon": "$media:1",
    "label": "$string:app_name"
  }
}

五、验证签名

构建 Release HAP 并检查签名:

bash 复制代码
# 构建 Release 版本
flutter build hap --release

# 检查生成的 HAP 是否已签名
# 成功签名后,安装到设备不会报 "签名验证失败"

六、调试模式 vs 发布模式

模式 签名要求 用途
Debug 可自动生成调试证书 日常开发
Profile 需要正式签名 性能分析
Release 必须使用正式签名 发布上架

在 build-profile.json5 中通过 buildModeSet 管理:

json5 复制代码
"buildModeSet": [
  { "name": "debug" },
  { "name": "profile" },
  { "name": "release" }
]

七、常见问题

Q: 签名后安装仍提示"签名验证失败"?

检查三点:

  1. .p7b Profile 中的 bundleName 与 app.json5 是否一致
  2. 证书是否过期
  3. 设备 UDID 是否在 Profile 的设备白名单中

Q: 能否在 CI/CD 中使用签名?

可以。将 .p12、.cer、.p7b 作为 CI Secret 存储,构建时动态写入 build-profile.json5。

小结

签名是鸿蒙开发中较容易出错的环节。关键要点:bundleName 一致性 、签名算法匹配 、证书有效期。掌握这些,签名配置就不再是拦路虎。

项目地址:https://gitcode.com/PengXiansheng/E-Brufen/blob/master/lib


相关推荐
码间留白10 小时前
AI 给的两个方案都被我否了:把 startIcon 与启动遮罩做成同一张图,鸿蒙 APP 冷启动零白屏
性能优化·uni-app·ai编程·harmonyos
二流小码农11 小时前
鸿蒙开发:证书只能创建3个,第4个应用怎么办
android·ios·harmonyos
瑞克-桑切斯11 小时前
Kubernetes 1.28 保姆级新手学习教程
运维·学习·docker·云原生·容器·kubernetes
程序员老刘12 小时前
跨平台开发地图 | 2026年11月
flutter·ai编程·客户端
kaixin_啊啊14 小时前
【三种鲑科鱼类比较基因组学分析鉴定出参与细胞内寄生菌鲑立克次体抗性的功能候选基因】论文学习
学习
威哥爱编程15 小时前
模拟面试智能体开发实战 12:每篇都能跑不等于接起来能跑,端到端联调收官把十一块拼图合成一个能用的智能体
python·agent·harmonyos
威哥爱编程15 小时前
模拟面试智能体开发实战 11:报告只躺在后端怎么复盘,把总评搬上手机还要适配大小屏
python·agent·harmonyos
CappuccinoRose16 小时前
Redis 学习文档
redis·后端·学习·缓存·session·非关系型数据库·gossip
我闪了个去16 小时前
一个 Scroll 撑起整个首页:HarmonyOS 7 懒加载布局把网格、瀑布流、吸顶分组装进一次滚动
harmonyos·arkts
qingwufeiyang_53017 小时前
Docker学习笔记2
笔记·学习