HarmonyOS 开通地图服务完整指南：AppGallery Connect 配置 + 签名 + 权限声明（手把手教程）
本文手把手教你在 AppGallery Connect（AGC）平台为 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（或快捷键Ctrl+Alt+Shift+S）。
步骤 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）
- Store file：选择
- 点击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}from'@kit.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 证书指纹中更新
- 重新申请 Profile
Q3：静态图返回空白图片
原因：可能是网络问题或坐标系不匹配。
解决：
- 确认设备已连接网络
- 确认使用 GCJ02 坐标系（中国大陆）
- 检查
module.json5中是否声明了ohos.permission.INTERNET
Q4：petalMaps API 调用无响应
原因：设备上未安装花瓣地图应用。
解决：
- 确认设备是 HarmonyOS 真机（非模拟器）
- 在应用市场搜索并安装"花瓣地图"
- 首次使用可能需要同意花瓣地图的用户协议
Q5：调试设备提示"签名不一致"
原因：调试设备未注册到 AGC 项目中。
解决：
- 在 AGC 的设备管理中添加设备的 UDID
- 重新申请调试 Profile（Profile 中会包含已注册设备列表）
九、完整配置检查清单
在运行地图功能前，逐项确认以下配置：
- AGC 中已开通地图服务
- 开通后已重新申请 Profile 文件
- 本地
.p7bProfile 文件已替换为最新版本 - DevEco Studio 签名配置正确（证书 + Profile）
module.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 控制台