适配鸿蒙 NEXT 与上架
本篇要点:把一个已经在微信、H5、App 三端跑通的 uni-app 项目,编译成能装到鸿蒙真机、并通过 AGC 审核的安装包。 前置文章:《离线优先:缓存、同步与冲突处理》解决了「没有网络时应用还能不能用」;这一章解决「装到一台新系统的手机上,应用还能不能跑」。
1 为什么需要它:卡住两天的是项目路径
先说一个反常识的现场:让团队卡最久的不是签名,也不是权限,是项目路径长度。
我们那个项目的目录叫 电商小程序-鸿蒙版。构建失败,报错信息里一个字都没提到中文。
鸿蒙 NEXT 是不兼容 Android 应用的新系统,安卓的 APK 装不上去。对 uni-app 项目来说,这意味着「多端」从三个端变成四个端,而第四个端的构建链、权限模型、签名体系跟前三个都不一样。从 HBuilderX 4.24 起可以运行到鸿蒙,但「能运行」和「能上架」之间隔着四道关:版本、路径、权限、签名。
这四道关有一个共同点:报错都离现场很远。版本不对,报的是 SDK 依赖校验失败;路径不对,报的是一句含糊的构建失败;权限没声明,能装上但调用时崩;签名不匹配,装都装不上。所以这一章按实际操作顺序讲,不按官方文档的文章顺序讲。基线是 HBuilderX 4.8x + DevEco Studio 5.1.x,截至 2026 年 11 月,版本口径以官方文档为准。
2 核心概念
2.1 两个编译器:HBuilderX 只是上层
定义:鸿蒙这条链路上有两套工具。HBuilderX 负责把 Vue 代码编译成鸿蒙工程,真正的打包由 DevEco Studio 自带的工具链(hvigor + 鸿蒙 SDK)完成。两边的版本必须对得上。
类比:HBuilderX 是把图纸翻译成施工图的设计院,DevEco 是施工队。设计院给的图纸规格和施工队的标准不一致,工地只会报「材料规格不符」,不会告诉你「设计院换了版本」。
反例:HBuilderX 升级了,DevEco 没动。报错是 compatibleSdkVersion 相关的依赖校验失败,看不出跟 IDE 版本有任何关系。
2.2 harmony-configs 是唯一合法入口
定义:首次执行【运行到鸿蒙】时,HBuilderX 在项目根目录生成 harmony-configs 目录。放进这个目录的文件,会在构建阶段被覆盖到自动生成的鸿蒙工程里——它是唯一的自定义配置入口。
反例:直接改 unpackage/dist/build/app-harmony 下的生成物。下次构建就被冲掉,改两小时等于没改。
2.3 路径与包名:两个不会报错的限制
定义:鸿蒙工具链构建时会产生很长的中间路径。实测留给鸿蒙工程目录本身的长度约 110 字符,如果走默认的 unpackage/dist/build/app-harmony,项目根目录路径最多只能用约 77 字符,且不能有中文或特殊字符。
包名(bundleName)必须与 AGC 上创建的 APP ID 一致,也必须与签名证书里的包名一致,三者对不上,签名就失败。
反例:目录名带中文(我们那个 电商小程序-鸿蒙版),路径长度没超,依然构建失败,报错不含任何提示。
2.4 权限两类,加一类「受限」
定义:鸿蒙权限分三类。system_grant 声明即可用,用户无感;user_grant 运行时弹窗询问;受限权限(restricted permission)要在 AGC 单独申请,审核通过后才可用,且必须写进签名证书的 ACL(Access Control List)。
类比:system_grant 像进小区大门,user_grant 像进自己家要开门,受限权限像进机房——不仅要钥匙,还要在门禁名单上。
反例:照抄 Android 的权限清单。READ_MEDIA、WRITE_MEDIA 在鸿蒙上不存在这个概念,写进去编译不过,改成「声明了就能读相册」更是错的——鸿蒙不允许应用直接读写用户目录。
2.5 JSVM 之后:原生能力只能走插件
定义:4.31 起逻辑层从 ArkTS 环境迁到 JSVM,只有 uts 插件仍留在 ArkTS 环境。这不是版本升级,是架构替换——等于中途换了发动机。
后果有三条:页面里不能再直接调鸿蒙原生接口,所有原生调用必须封进 uts 插件(utssdk/app-harmony);不能再用 DevEco Studio 打断点,要靠 setWebDebuggingAccess + Chrome DevTools;受 JSVM 限制只能跑在 arm64 设备上,x86_64 模拟器要升到 HarmonyOS 5.1.1(19) Beta1 及以上。
反例:在业务页面里散落 #ifdef APP-HARMONY 加 ohos.* 调用。第一个原生能力接进来时能跑,第五个进来时已经没人说得清哪些代码是鸿蒙专属的。
3 动手实践
任务:把项目编到鸿蒙真机上跑通,打出签名包,并准备好审核需要的材料。
3.1 先对齐版本,别急着改代码
表 11-1 是本篇写作时确认过的版本对应关系,4.31 那行要特别看一眼。
表 11-1 HBuilderX 与 DevEco Studio 的版本对应
| HBuilderX | DevEco Studio 要求 | 关键能力变化 |
|---|---|---|
| 4.24+ | 5.0.3.400+ | 支持运行到鸿蒙平台 |
| 4.27+ | — | 鸿蒙工程模板内置,运行到鸿蒙时自动创建工程目录 |
| 4.28+ | — | 支持【发行】→【App-Harmony-本地打包】 |
| 4.31+ | 5.0.3.800+ | 逻辑层从 ArkTS 改到 JSVM,架构级变更;同版本构建的包不再支持 x86_64 |
| 4.41+ | — | 运行到鸿蒙支持热刷更新、日志回源代码 |
| 4.43+ | — | manifest.json 的 versionName / versionCode 生效于鸿蒙 |
| 4.51+ | — | 需在 build-profile.json5 的 products 中配 compatibleSdkVersionStage: "beta6" |
| 4.61+ | — | 可自定义鸿蒙工程目录、签名可视化配置、自动申请调试证书 |
| 4.81+ | 5.1.0.849+ | 逻辑层 JSVM 移到独立子线程,避免阻塞主线程 |
# 环境自检:三样东西的版本必须都在表 11-1 的同一行上
hvigorw --version 2>/dev/null || echo "hvigor 未在 PATH,用 DevEco 自带终端"
node -v
ls ~/Library/Huawei/Sdk 2>/dev/null || ls "C:/Program Files/Huawei/DevEco Studio/sdk"运行结果(一次真实的错配现场):
hvigor 5.0.3
v18.20.4
sdk/12 sdk/15
# 报错:compatibleSdkVersion 12 与 DevEco 5.0.3 要求不符4.27 那行我一开始也记错了。它的意思是「工程模板内置」,不是「从此支持鸿蒙」——支持能力从 4.24 就有了。真正被官方列为架构级改动的只有 4.31、4.51、4.81 三档。
四个必须先接受的限制:只支持 Vue3,Vue2 项目先迁;不支持 plus,所有 plus.* 在鸿蒙端不可用;支持 nvue,但 nvue 编译到鸿蒙后是按 Web 方式渲染并注入默认样式,不是原生渲染;系统要求 API 12 以上,模拟器建议 API 20+,低于 API 19 的模拟器跑不了 uni-app 项目。
顺带把 uni-app x 的口径分开记:x 的 VDOM 模式最低鸿蒙 API 14,蒸汽模式最低 API 20(鸿蒙 6.0+),低于目标版本直接编译报错。两套东西别混着查文档,混着查的代价是多花一整天。
3.2 把工程目录挪出项目根目录
路径问题的根治办法不是改项目名,是挪构建目录。4.61 起可以这么配:
// .hbuilderx/launch.json(项目根目录,不存在则新建)
{
"version": "1.0",
"configurations": [
{
"type": "uni-app:app-harmony",
"distPathDev": "D:/harmony-project-dev",
"distPathBuild": "D:/harmony-project-build"
}
]
}预期输出(重新运行到鸿蒙之后,项目根目录应该只剩源码和配置):
$ tree -L 1 .
.
├── harmony-configs
├── src
├── package.json
└── .hbuilderxdistPathDev 用于调试运行,distPathBuild 用于发行打包。目录不必预先存在,HBuilderX 会创建;已存在时可能被删除重建——所以别指向有其它文件的目录,它做的是重建不是合并。
3.3 包名、图标与启动图
// src/manifest.json
{
"app-harmony": {
"distribute": {
"bundleName": "com.example.shop", // 必须与 AGC 上创建的 APP ID 一致
"icons": {
"foreground": "static/harmony/fg.png",
"background": "static/harmony/bg.png"
},
"splashScreens": {
"startWindowBackground": "#FFFFFF",
"startWindowIcon": "static/harmony/splash.png"
}
}
}
}预期输出(打包日志里会回显实际使用的包名):
[App-Harmony] bundleName = com.example.shop
[App-Harmony] versionName = 1.4.0 / versionCode = 140distribute 下面还有 modules,用于配定位(uni-location)、地图(uni-map)、登录鉴权(uni-oauth)、支付(uni-payment)、分享(uni-share)。这些模块的 key 要去对应厂商单独申请。微信支付、高德地图的鸿蒙 SDK 和 Android 是两套,key 不通用,排期时这块最容易被低估。
3.4 权限成对声明
配置位置固定在 harmony-configs/entry/src/main/module.json5:
{
"module": {
"requestPermissions": [
{ "name": "ohos.permission.INTERNET" },
{
"name": "ohos.permission.APPROXIMATELY_LOCATION",
"reason": "$string:location_reason",
"usedScene": { "abilities": ["EntryAbility"], "when": "inuse" }
},
{
"name": "ohos.permission.LOCATION",
"reason": "$string:location_reason",
"usedScene": { "abilities": ["EntryAbility"], "when": "inuse" }
}
]
}
}预期输出(reason 写成中文字面量时,编译直接失败):
error: The 'reason' field must be a string resource reference, e.g. $string:location_reason三条实打实的经验。定位权限必须精准加模糊成对声明,只声明 LOCATION 会被上架审核驳回。READ_MEDIA / WRITE_MEDIA 已废弃,选图用 uni.chooseImage、选文件用 uni.chooseFile(背后封装了系统 Picker,不需要申请权限),存图用 uni.saveImageToPhotosAlbum。reason 必须是字符串资源引用,指向 resources/base/element/string.json 里的键。
3.5 签名三件套与 UDID 绑定
签名需要的材料是固定的三个文件、两个密码、一个别名,作用见表 11-2。
表 11-2 签名三件套的职责
| 文件 | 扩展名 | 来源 | 作用 |
|---|---|---|---|
| 私钥库 | .p12 | 自己生成 / DevEco 自动申请 | 保存签名私钥,双层密码保护 |
| 证书 | .cer | 华为 AGC 颁发 | 证明开发者身份 |
| 签名描述文件 | .p7b | 华为 AGC 颁发 | 绑定包名、ACL 权限、调试设备列表 |
# 取设备 UDID,需先装鸿蒙 SDK 的 hdc(DevEco Studio 自带)
hdc shell bm get -u运行结果:
8A3F1C2D9E7B4056调试证书与包名、设备 UDID 双向绑定:签名描述文件里没有的设备,装不上。所以每换一台测试机,都要回 AGC 把 UDID 加进去重新下载 Profile。
图 11-1 从建 APP ID 到提交审核的完整路径
如图 11-1 所示,两条分支只差在证书怎么来。用了受限权限(读相册、后台定位这类)就只能手动走一遍:4.61+ 的自动申请调试证书会调 AGC API 完成申请与配置,但自动申请拿不到含 ACL 权限的证书。
流程里唯一不能省的是真机 debug 验证。模拟器一般不需要签名,真机和 ACL 场景才需要,所以模拟器跑通不代表能装到真机。另外 AGC 对每个账号可创建的证书数量有限制,删证书会让基于它的 Profile 一起失效,测试阶段别反复申请。
3.6 把原生差异关进 adapter
// src/adapter/native.js
// 鸿蒙端原生能力统一从自建 uts 插件进入(插件内 utssdk/app-harmony 调 @ohos.vibrator)
// 页面层不出现任何 ohos.* 调用
import { vibrate as utsVibrate } from '@/uni_modules/uts-haptic'
export function vibrate(type = 'light') {
// #ifdef APP-HARMONY
return utsVibrate({ type })
// #endif
// #ifdef APP-PLUS
return plus.device.vibrate(200)
// #endif
// #ifdef H5 || MP
return false // 无振感能力,静默降级
// #endif
}预期输出(同一份业务代码在两端的行为):
[APP-HARMONY] vibrate({type:"light"}) -> ok
[H5] vibrate() -> false(静默降级,无报错)这段代码的重点不是振动,是边界。#ifdef APP-HARMONY 只出现在 adapter 文件里,业务层永远只看到 vibrate()。哪天插件实现换了,改动范围是一个文件,不是全站搜索。uts 插件的写法在《原生能力:UTS 插件与原生插件开发》 原生能力:UTS 插件与原生插件开发 里讲过,鸿蒙端只是多一个 utssdk/app-harmony 目录。
4 常见误解
以为模拟器跑通就等于能上架。 模拟器不需要签名、不校验 UDID、也不走 ACL,三道关它全绕过了。它能证明页面能渲染,证明不了包能装到用户手机上。
以为鸿蒙权限可以照抄 Android。 两套模型不一样:Android 的存储权限在鸿蒙上没有对应物,鸿蒙用系统 Picker 代替;定位权限要成对声明;受限权限要进证书 ACL。照抄 Android 清单是这条路上最贵的习惯。
以为路径超长会报「路径太长」。 不会。报错只写构建失败,中文目录也一样。所以第 3.2 节把构建目录挪出去不是优化,是绕开一个不给你提示的坑。
以为升级工具链后可以直接跑。 升级 HBuilderX 后首次运行鸿蒙,我们遇到过一次 ninja: error: failed recompaction 和产物错乱,选「清空缓存」重跑才好。触发条件我没搞清,但升级后的第一次运行不该信任缓存。
5 小结
- 鸿蒙适配是四道关:版本、路径、权限、签名。四道关的报错都离现场很远,所以顺序比技巧重要。
- HBuilderX 与 DevEco 的工具链版本必须对齐;4.31 是架构级变更(ArkTS → JSVM),不是普通升级。
harmony-configs是唯一合法配置入口,改unpackage下的生成物等于没改。- 项目根目录路径控制在 77 字符以内、不含中文;4.61+ 用
launch.json把鸿蒙工程目录挪出去更彻底。 - 权限分
system_grant、user_grant、受限三类;定位要成对声明,reason必须用$string:引用。 - 用到 ACL 权限就必须手动申请证书;签名三件套的包名要与 AGC 的 APP ID 一致,设备 UDID 要进 Profile。
- 原生差异关进 adapter,页面层不出现
ohos.*,#ifdef的密度才控得住。
6 相关文章
到这一章,四个端都能出包了。但端一多,工程本身开始出问题:三个小组共用一个 manifest.json,每个发版周期都要在这一个文件上解三四次冲突;发布动作绑在某台开发机的本地环境上,换人接手只能靠口头交接。《进阶:多端项目结构与 CI 自动发布》讲多端项目的目录结构怎么分层、渠道 appid 怎么在构建期注入,以及 CI 能自动到哪一步就必须停下等人。