前言

网上绝大多数教程存在操作顺序颠倒的致命问题:先创建Profile再开通MapKit能力,会直接导致调试文件不包含地图权限,运行必报403鉴权错误。

整体流程总览

新建AppID → 开通MapKit+定位能力 → 生成p12密钥+CSR文件 → 后台上传CSR获取cer证书 → 录入真机UDID → 生成绑定地图权限的调试Profile(p7b) → IDE配置全套签名 → 提取SHA256指纹填入开发者后台 → 复制ClientID写入工程 → 卸载旧安装包清理缓存 → 重新编译真机运行


一、鸿蒙开发者中心新建APP ID

  1. 点击头像隔壁的开发者中心进入
  2. 应用类型:带元服务卡片选HarmonyOS应用;纯元服务才选元服务
  3. 应用包名【重中之重】:必须和DevEco工程包名完全一致(大小写、字符不能有任何差异),全局唯一,不清楚的可以在设置——项目结构——签名配置里面看到
  4. 勾选设备:仅勾选手机,其余设备取消勾选(按自己实际情况)


二、开放能力:先开启MapKit+定位服务(核心前置步骤)

【最高优先级坑点】必须先开通MapKit能力,再生成Profile! 如果先生成Profile再开通服务,旧p7b文件不携带地图权限,直接403,只能重新生成Profile。

操作步骤:

  1. 进入【开发者管理】→【开放能力管理】,选中刚创建的应用
  2. 勾选:地图服务(Map Kit)、定位服务(自己往下划划看)
  3. 保存并提交生效

三、DevEco Studio生成p12密钥库+CSR证书文件

  1. 顶部菜单:Build → Generate Key and CSR
  2. 点击New新建密钥库
    • 保存路径:禁止中文、空格、C盘深层目录,建议桌面新建cert文件夹存放证书
    • 密钥库密码:≥8位,字母+数字+符号,务必留存
    • 别名alias:自定义,例如mapkit_debug
    • 有效期:25年
  3. 导出CSR证书申请文件,最终得到2个文件:
    • xxx.p12:私钥密钥库,本地妥善保管,严禁外传
    • xxx.csr:证书申请文件,用于上传开发者后台

四、后台上传CSR,获取调试cer证书

  1. 左侧菜单【ID、证书和Profile】→【证书】→【新增证书】
  2. 证书名称:自定义,例如mapkit_debug_cert
  3. 证书类型:调试证书(绝对不要选发布证书)
  4. 上传刚才导出的.csr文件,提交后立即审核通过,下载.cer证书

备注:一个实名账号最多3个调试证书,有效期1年。


五、注册真机UDID(模拟器无需此步骤)

  1. 左侧菜单【设备】→【新增设备】
  2. 填写设备名称、真机UDID,完成注册
  3. 建议备注手机型号,多台真机调试方便区分(hdc如果你没提前配置到path就直接在软件终端去进行)

六、创建调试Profile描述文件(p7b)

前置条件校验:MapKit能力已开通、调试证书已创建、真机UDID已注册。

  1. 左侧菜单【Profile】→【新增Profile】
  2. 选中对应应用,核对包名和工程完全一致
  3. Profile名称:自定义,类型选择调试(按你自己的需求)
  4. 选中第四步创建的调试证书,勾选已注册的真机设备
  5. 提交,下载.p7b Profile文件

七、DevEco Studio项目签名配置

  1. 打开 File → Project Structure → Signing Configs
  2. 取消勾选【自动生成签名文件】,使用手动证书
  3. 依次填入文件与密码:
    • 密钥库文件:.p12
    • 密钥库密码、密钥别名、密钥密码
    • Profile文件:.p7b
    • 证书文件:.cer
  4. 点击【应用】→【确定】保存配置

八、提取SHA256指纹并配置到开发者后台

8.1 keytool命令获取指纹(复制直接用)

打开CMD或者直接在Deveco的终端,执行下面命令,替换为你的p12完整路径:

keytool -list -v -keystore C:\Users\liang\Desktop\cert\mapkit_debug.p12

输入密钥库密码,找到SHA-256字段,把字符串里所有冒号:全部删除,只保留大写字母+数字。

8.2 后台录入指纹+复制ClientID

  1. 打开AppID应用详情 → 添加公钥指纹,粘贴处理好的SHA256字符串
  2. 复制页面的OAuth 2.0客户端ID(Client ID),后续写入代码

同步延迟:新增指纹、更新Profile后,华为服务器存在几分钟~数小时延迟,刚配置完就运行大概率报403,优先等待生效,不要反复改配置。


九、module.json5配置ClientID

把后台拿到的Client ID填入MapKit对应配置节点。


十、清理缓存+卸载旧安装包(解决签名缓存导致403)

方式1(推荐):真机手动卸载

长按应用图标彻底卸载,禁止直接覆盖安装旧包,旧签名缓存会持续鉴权失败。

方式2:hdc命令卸载(IDE终端执行)

hdc uninstall com.atomic.service.6917621937198970317

输出uninstall bundle successfully.代表卸载成功。


十一、重新构建项目

  1. Build → Clean Project
  2. 等待清理完成后,执行 Build → Rebuild Project
  3. 编译产物路径:entry/build/outputs/hap/default/entry-default-signed.hap

十二、真机运行测试

  1. 设备下拉选择已注册UDID的真机
  2. 点击Run按钮安装HAP并启动应用
  3. 查看日志,验证地图正常加载;出现403对照下方排错清单逐项核对。

三、踩坑清单和排错优先级(403报错对照排查)

高频错误项

  1. 顺序颠倒:先生成Profile,后开通MapKit → 解决:先开能力,重新生成p7b文件
  2. 覆盖安装不卸载旧包:签名缓存残留,必报403 → 解决:彻底卸载应用再重新安装
  3. SHA256指纹没有删除冒号:后台校验直接失败
  4. 后台AppID包名 ≠ 工程包名:大小写、字符必须一字不差
  5. 误用发布证书做真机调试:调试只能使用调试证书+调试Profile
  6. 证书路径包含中文、空格:IDE签名直接报错

403鉴权失败排查顺序

  1. 核对前后包名完全一致
  2. 确认p12/cer/p7b是同一套调试证书
  3. 确认SHA256已经去掉所有冒号
  4. 确认Profile是开通MapKit之后才创建的
  5. 真机彻底卸载旧应用,清除缓存
  6. 等待AGC服务器同步生效(延迟等待)
Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐