使用 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 中：
Build → Generate Key and CSR- 填写信息：别名（如
aaa）、密码、组织名称等 - 生成
.csr和.p12文件
或者在命令行使用 keytool：
keytool-genkeypair-aliasaaa-keyalgEC-sigalgSHA256withECDSA\-keystorefirstproject.p12-storetypePKCS12-validity3650⚠️ E-Brufen 使用SHA256withECDSA算法——这是鸿蒙推荐的签名算法，兼顾安全性和性能。
步骤 2：申请证书
- 登录 AppGallery Connect
- 进入
证书管理 → 新增证书 - 上传刚才生成的
.csr文件 - 下载颁发的
.cer证书
申请地址:https://developer.huawei.com/consumer/cn/service/josp/agc/index.html#
步骤 3：申请 Profile
- 在 AppGallery Connect 中进入
Profile 管理 - 创建新的 Profile，选择：
- 证书（刚才申请的
.cer） - 设备类型（phone）
- 应用包名：
com.flutter.brufen
- 证书（刚才申请的
- 下载
.p7bProfile 文件
三、配置 build-profile.json5
将签名材料路径写入ohos/build-profile.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 一致：
{ "app": { "bundleName": "com.flutter.brufen", "vendor": "example", "versionCode": 1000000, "versionName": "1.0.0", "icon": "$media:1", "label": "$string:app_name" } }五、验证签名
构建 Release HAP 并检查签名：
# 构建 Release 版本flutter build hap--release# 检查生成的 HAP 是否已签名# 成功签名后，安装到设备不会报 "签名验证失败"六、调试模式 vs 发布模式
| 模式 | 签名要求 | 用途 |
|---|---|---|
| Debug | 可自动生成调试证书 | 日常开发 |
| Profile | 需要正式签名 | 性能分析 |
| Release | 必须使用正式签名 | 发布上架 |
在build-profile.json5中通过buildModeSet管理：
"buildModeSet": [ { "name": "debug" }, { "name": "profile" }, { "name": "release" } ]七、常见问题
Q: 签名后安装仍提示"签名验证失败"？
检查三点：
.p7bProfile 中的 bundleName 与app.json5是否一致- 证书是否过期
- 设备 UDID 是否在 Profile 的设备白名单中
Q: 能否在 CI/CD 中使用签名？
可以。将.p12、.cer、.p7b作为 CI Secret 存储，构建时动态写入 build-profile.json5。
小结
签名是鸿蒙开发中较容易出错的环节。关键要点：bundleName 一致性、签名算法匹配、证书有效期。掌握这些，签名配置就不再是拦路虎。
项目地址:https://gitcode.com/PengXiansheng/E-Brufen/blob/master/lib