使用 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：

bash 复制代码

keytool -genkeypair -alias aaa -keyalg EC -sigalg SHA256withECDSA \
  -keystore firstproject.p12 -storetype PKCS12 -validity 3650

⚠️ 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
下载 .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: 签名后安装仍提示"签名验证失败"？

检查三点：

.p7b Profile 中的 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