HarmonyOS 开通地图服务完整指南AppGallery Connect 配置 签名 权限声明手把手教程本文手把手教你在 AppGallery ConnectAGC平台为 HarmonyOS 应用开通地图服务Map Kit涵盖 DevEco Studio 一键配置、AGC 网站手动开通、签名证书重新申请、权限声明等完整流程。适合首次接入 Map Kit 的开发者。效果一、为什么需要开通地图服务HarmonyOS Map Kit包括staticMap静态图、petalMaps拉起地图应用等 API依赖华为 AGC 平台的鉴权机制。在调用任何地图 API 前必须先在 AGC 中开通地图服务并将授权信息写入应用的签名 Profile 文件中。未开通地图服务时调用 API 会出现以下错误error code 60001地图服务未开通error code 60002签名指纹校验失败静态图请求返回空结果或拒绝响应二、开通方式概览提供两种开通方式根据开发阶段选择方式适用场景操作步骤方式一DevEco Studio快速开发调试File → Project Structure → Signing Configs → 勾选 Map Kit方式二AGC 网站生产环境 / 团队协作登录 AGC → 项目 → 应用 → 开放能力 → 开启地图服务三、方式一通过 DevEco Studio 开通推荐新手步骤 1打开项目结构配置在 DevEco Studio 中点击菜单栏File → Project Structure或快捷键CtrlAltShiftS。步骤 2进入签名配置在弹出的对话框中左侧选择Signing Configs选项卡。步骤 3勾选 Map Kit 开放能力在签名配置页面中找到Open Capabilities区域勾选Map Kit选项。如果看不到 Map Kit 选项请确认DevEco Studio 版本 ≥ 6.0.0 Release已登录华为开发者账号项目已关联 AGC 项目步骤 4应用配置点击Apply按钮DevEco Studio 会自动完成以下操作在 AGC 中开启地图服务开关重新申请包含地图服务授权的 Profile 文件更新本地签名配置步骤 5确认成功Apply 完成后在签名配置页面确认 Map Kit 已显示为已启用状态。四、方式二通过 AppGallery Connect 网站开通步骤 1登录 AGC打开浏览器访问 AppGallery Connect使用华为开发者账号登录。步骤 2选择项目在首页点击我的项目从项目列表中选择你的项目。步骤 3选择应用在项目详情页中找到应用列表选择需要开通地图服务的应用。步骤 4进入开放能力管理在应用详情页左侧菜单中选择开发与服务 → 开放能力或直接搜索地图。步骤 5开启地图服务在开放能力列表中找到地图服务Map Kit点击右侧的开启按钮。重要提示开启地图服务后之前生成的 Profile 文件会失效必须重新申请五、签名配置关键步骤无论使用哪种方式开通地图服务都需要重新申请签名文件将地图服务授权写入 Profile 中。5.1 调试阶段签名配置5.1.1 申请调试证书打开 DevEco Studio →File → Project Structure → Signing Configs选择debug配置在Signing Configs中确保Automatically generate signature已勾选如果尚未生成证书点击Apply自动生成5.1.2 注册调试设备在 AGC 中选择用户与访问 → 设备管理添加调试设备的 UDID可通过 DevEco Studio 的 Device Manager 查看每个项目最多注册 100 台调试设备5.1.3 重新申请调试 Profile开通地图服务后必须执行此步骤在 AGC 中选择项目设置 → 应用信息找到Profile 管理区域点击重新申请或新增 Profile确保新 Profile 中包含 Map Kit 能力下载新的 Profile 文件并替换本地文件5.1.4 DevEco Studio 手动签名配置打开File → Project Structure → Signing Configs取消勾选Automatically generate signature手动填入Store file选择.p12签名证书文件Store password签名证书密码Key alias密钥别名Key password密钥密码Profile file选择重新申请的.p7bProfile 文件Sign alg选择签名算法推荐SHA256withECDSA点击OK保存5.2 发布阶段签名配置发布上架应用市场时需要使用发布证书和发布 Profile在 AGC 中申请发布证书与调试证书不同使用发布证书申请发布 Profile包含 Map Kit 能力在 DevEco Studio 的release签名配置中填入发布证书和 Profile六、权限声明在应用的module.json5中声明网络访问权限这是调用地图 API 的必要条件// entry/src/main/module.json5 { module: { requestPermissions: [ { name: ohos.permission.INTERNET, reason: $string:permission_internet_reason } ] } }如果需要根据用户位置显示附近地图还需要声明位置权限{ name: ohos.permission.APPROXIMATELY_LOCATION, reason: $string:permission_location_reason, usedScene: { abilities: [EntryAbility], when: inuse } }同时在resources/base/element/string.json中添加权限说明文本{name:permission_internet_reason,value:加载地图数据需要网络访问权限}七、验证地图服务是否开通成功完成配置后可以通过以下代码验证地图服务是否正常工作import{staticMap}fromkit.MapKit;// 调用一个简单的静态图请求来验证constoption:staticMap.StaticMapOptions{location:{latitude:39.9167,longitude:116.3907},zoom:10,imageWidth:400,imageHeight:300,scale:1};staticMap.getMapImage(option).then((){console.info(地图服务验证通过);}).catch((error:Error){console.error(地图服务验证失败:,error.message);// 根据错误信息排查配置问题});验证成功标志控制台输出地图服务验证通过且getMapImage正常返回 PixelMap。八、常见问题排查Q1报错 60001地图服务未开通原因AGC 中未开启地图服务或开启后未重新申请 Profile。解决确认 AGC 中地图服务已开启重新申请 Profile 文件这是最常见的遗漏步骤替换本地.p7b文件后重新编译Q2报错 60002签名校验失败原因签名证书指纹与 AGC 注册的不一致。解决在 DevEco Studio 中查看当前签名证书的 SHA256 指纹在 AGC 的项目设置 → 应用信息 → SHA-256 证书指纹中更新重新申请 ProfileQ3静态图返回空白图片原因可能是网络问题或坐标系不匹配。解决确认设备已连接网络确认使用 GCJ02 坐标系中国大陆检查module.json5中是否声明了ohos.permission.INTERNETQ4petalMaps API 调用无响应原因设备上未安装花瓣地图应用。解决确认设备是 HarmonyOS 真机非模拟器在应用市场搜索并安装花瓣地图首次使用可能需要同意花瓣地图的用户协议Q5调试设备提示签名不一致原因调试设备未注册到 AGC 项目中。解决在 AGC 的设备管理中添加设备的 UDID重新申请调试 ProfileProfile 中会包含已注册设备列表九、完整配置检查清单在运行地图功能前逐项确认以下配置AGC 中已开通地图服务开通后已重新申请 Profile 文件本地.p7bProfile 文件已替换为最新版本DevEco Studio 签名配置正确证书 Profilemodule.json5中声明了ohos.permission.INTERNET使用 HarmonyOS 真机运行非模拟器设备已安装花瓣地图应用使用 petalMaps 功能时坐标系使用 GCJ02中国大陆或 WGS84海外十、总结开通地图服务的核心流程可以总结为三步开通服务在 AGC 或 DevEco Studio 中开启 Map Kit重新签名申请包含地图能力的新 Profile 文件声明权限在module.json5中添加网络权限其中第 2 步最容易被遗漏——很多开发者开启了地图服务但没有重新申请 Profile导致运行时一直报 60001 错误。记住每次在 AGC 中修改开放能力后都必须重新申请 Profile 文件。参考文档开通地图服务官方指南手动签名配置AppGallery Connect 控制台参考文档开通地图服务官方指南手动签名配置AppGallery Connect 控制台