作为一个靠 uni-app 做跨端开发的 “老玩家”，之前已经用它上线了五款 Vue2 的 App —— 不过这次多了个新目标：适配鸿蒙 NEXT 系统。目前成功打包上架鸿蒙两款APP，中间踩了不少坑，也攒了些实打实的经验，今天就把整个过程捋一捋，希望能帮到同样在做鸿蒙适配的朋友。
一、技术选型：为什么选 uni-app 做鸿蒙开发？
其实最开始也纠结过要不要用鸿蒙原生开发，但手里的项目是现成的 Vue2 代码，还要兼顾微信小程序 ——uni-app 的 “一次开发多端跑” 刚好戳中需求。后来查了文档才知道，uni-app 对鸿蒙 NEXT 的支持已经比较成熟了，尤其是 UTS 插件能直接调用鸿蒙原生能力，不用从头写原生代码，省了不少事。这也是我最终敲定用 uni-app 做适配的核心原因：能复用老项目代码，还能兼顾跨端，效率比重新开发高太多。
二、鸿蒙迁移实战
1.手里的 App 都是 Vue2 写的，但鸿蒙只支持 Vue3 的 uni-app 项目，所以第一步就得把 Vue2 迁移到 Vue3。需要适配vue3包括项目代码和相关组件。
首先是生命周期，Vue2 里的beforeDestroy得改成beforeUnmount，destroyed改成unmounted，一开始没注意，控制台报了一堆错；然后是 v-model，Vue3 里父子组件传值得写成:modelValue="xxx"和@update:modelValue="xxx=$event"，之前的写法直接用不了；还有路由，Vue2 里是new VueRouter()，Vue3 得用createRouter和createWebHistory，这些基础语法得逐个核对。
组件方面，之前用的 Element UI 在 Vue3 里不兼容，只能换成 Element Plus。这里要注意，Element Plus 的引入方式和 Element UI 不一样，得在 main.js 里用createApp(App).use(ElementPlus)，还得单独引入样式文件，不然组件样式会乱。我当时漏引了样式，页面加载出来全是裸奔的 HTML 元素，排查了半天才发现问题。
2.引入harmony-configs，注意里面的client_id的取值。
3.华为登录：必须做的 “硬性要求”
鸿蒙上架有个规定：只要 App 接入了第三方登录（比如微信、QQ 登录），就必须集成华为登录。不过好在 uni-app 已经封装了华为登录的 API，不用自己写原生代码，直接调用uni.login({provider: 'huawei'})就行。
但这里有个细节：调用登录前得确保harmony-configs已经初始化，不然会报 “client_id 未配置” 的错。我当时是在 main.js 里先初始化harmony-configs，再调用登录接口，代码大概是这样：
import harmonyConfigs from '@dcloudio/harmony-configs'
// 初始化，client_id从AGC拿
harmonyConfigs.init({
clientId: '这里填你的client_id',
scope: 'openid profile email'
})
// 后续调用华为登录
uni.login({
provider: 'huawei',
success: (res) => {
// 拿到code后去后端换token
console.log('华为登录code：', res.code)
},
fail: (err) => {
uni.showToast({ title: '登录失败：' + err.errMsg, icon: 'none' })
}
})
4.发布到鸿蒙开发平台，开发服务中要添加发布证书/调试证书 SHA256证书/公钥指纹。
迁移完代码，就得搭鸿蒙开发环境了。首先得装 DevEco Studio，我下的是 5.0 版本。然后是证书 —— 这是我踩的第二个 “坑”。
鸿蒙开发需要调试证书和发布证书，还得配置 SHA256 指纹。步骤其实不复杂：先在 DevEco Studio 里生成.p12 格式的密钥库，再用这个密钥库生成.csr 文件，然后去华为 AGC 平台（鸿蒙开发平台）上传.csr，申请发布证书（.cer 格式）和 Profile 文件（.p7b 格式）。最后要在 AGC 的 “应用信息” 里填 SHA256 指纹 —— 这里一定要注意，调试证书和发布证书的指纹要分开填，我一开始把调试指纹当成发布指纹填了，导致后来打包发布版登录失败，折腾了好久才发现。
另外，引入harmony-configs的时候，里面的client_id得从 AGC 平台拿 —— 在 “我的应用” 里找到对应的 App，进入 “配置” 页面，OAuth 2.0 客户端 ID 就是client_id，填错了后续华为登录会调不通。
5.鸿蒙隐私政策完善:请在相应场景补充HarmonyOS NEXT操作系统的介绍/选项/设备标识符等信息。可参考《审核指南》第1.14项：https://developer.huawei.com/consumer/cn/doc/app/50104-01
三、鸿蒙原生能力：uts实现实况窗接入
鸿蒙 NEXT 的实况窗是个特色功能，我做的App 是计时工具，刚好能用实况窗显示剩余时间，提升用户体验。这里就用到了 uni-app 的 UTS 插件，分享下具体怎么集成的。
UTS 插件结构
uni_modules/harmony-liveview/
├── package.json # 插件配置
├── utssdk/
│ ├── interface.uts # TypeScript 接口定义
│ └── app-harmony/
│ └── index.uts # 鸿蒙平台实现
├── readme.md # 使用文档
├── changelog.md # 更新日志
└── 使用说明.md # 本文件核心 API
isLiveViewEnabled()- 检查实况窗是否可用startLiveView()- 启动实况窗updateLiveView()- 更新实况窗显示pauseLiveView()- 暂停/继续计时stopLiveView()- 停止实况窗
完整流程:
1.UTS 插件创建：自己搭了个简单的插件
我在uni_modules下建了个harmony-liveview文件夹，专门放实况窗相关的代码。结构很简单：utssdk文件夹里放接口定义（interface.uts）和鸿蒙原生实现（app-harmony/index.uts），还有个package.json配置插件信息。
interface.uts主要定义了几个核心方法的接口，比如检查实况窗是否可用、启动、停止、更新，这样 Vue 组件里调用的时候有类型提示；
index.uts是真正对接鸿蒙原生 LiveView API 的地方，比如startLiveView方法里，会先检查设备是否支持实况窗，再调用鸿蒙的LiveViewManager.start()启动，还加了定时更新数据的逻辑，默认 10 秒更一次。
2.uniapp vue组件集成：和业务逻辑绑在一起
我的计时页面是clock.vue，在里面导入了 UTS 插件的方法，然后把实况窗的启动 / 停止和计时功能绑在一起：用户点 “开始” 按钮，调用startTimer的时候，自动触发startHarmonyLiveView启动实况窗；点 “停止” 的时候，调用stopTimer，同时触发stopHarmonyLiveView停止实况窗。这里要注意，启动实况窗前得先调用isLiveViewEnabled()检查设备是否支持，不然在不支持的设备上会报错。我还加了个提示，不支持的话就弹个 Toast 告诉用户，体验会好一些。
3.本地调试，先申请权限也需要添加设备token，参考官方文档，添加后才能进行测试，只有调试没有问题才可以提交单独的实况窗开通审核。
4.实况窗上线：审核比想象中严格
实况窗要上线，得先在 AGC 申请权限，还得提交设计方案 —— 包括功能场景、界面布局图、资源占用情况。我当时提交的方案里，因为没写清楚 “为什么需要实时更新”，被审核打回来了，后来补充了 “计时工具需要用户在桌面就能看到剩余时间，不用打开 App” 的说明，才通过。
另外，本地测试的时候，要在 AGC 里添加测试设备的 Token，不然实况窗调不起来。我一开始没加，以为是代码有问题，查了半天文档才知道要配置设备 Token，这点大家要注意。
UTS代码片段:
参考资料:
- 鸿蒙 LiveView Kit 官方文档
- uni-app UTS 插件开发文档
- https://developer.huawei.com/consumer/cn/codelabsPortal/carddetails/tutorials_NEXT-Live-View-Flight
- https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/liveview-create-locally
四、上架前的 “避坑指南”：我踩过的 3 个关键问题
1.发布版白屏：云调试救了我
本地调试的时候一切正常，但打包发布版提审，鸿蒙审核那边反馈说白屏。我自己下载发布包安装，也遇到了同样的问题，不知道哪里出了错。后来想起 AGC 有个 “云调试” 功能，能选不同型号的鸿蒙设备测试，还能看日志。我用云调试跑了一遍，发现是 SHA256证书/公钥指纹的问题。
2.登录失败：指纹配置错了
调试版登录没问题，但发布版一直报 “Fingerprint verification error”。查了 AGC 的日志，发现是发布证书的 SHA256 指纹没配置 —— 我之前只填了调试指纹，发布指纹忘了填。补填之后，还得在manifest.json里把versionCode改大一点（比如从 100 改成 101），再让测试的手机把旧版本删掉，不然缓存会导致配置不生效。
3.鸿蒙备案：提前一周做准备
鸿蒙上架前必须完成 鸿蒙App 备案。备案提交后，审核界面的校验不是立马生效的，我当时等了差不多 1 天半才显示备案通过。
五、总结：几个实用的小经验
1.上线前可以用 AGC 的云调试测一遍，很多本地测不出来的问题（比如白屏、登录失败），云调试能快速帮你找到原因；
2.Vue2 迁 Vue3 的时候，别着急删老代码，先建个分支慢慢改，遇到问题还能回滚；
3.实况窗的设计方案要写详细，尤其是 “为什么需要这个功能”，不然审核容易被打回；
4.证书和指纹一定要区分调试版和发布版，别搞混了。
总的来说，用 uni-app 适配鸿蒙 NEXT 的流程不算复杂，只要把 Vue3 迁移、证书配置、华为登录这几个关键点搞定，后续上架就顺理成章了。中间虽然踩了不少坑，但解决问题的过程也是技术成长的过程。希望这篇记录能帮到大家，也欢迎大家在评论区分享自己的适配经验，一起交流进步！
