UniApp Vue3 开发鸿蒙（HarmonyOS）App 全流程指南

UniApp 目前支持在鸿蒙系统（HarmonyOS）上进行应用开发，从 HBuilderX 4.27 版本开始，UniApp 支持将 Vue3 项目编译到鸿蒙平台（Harmony Next）。开发者可以通过 UniApp 框架快速开发适配鸿蒙系统的应用，但 Vue2 项目需要先迁移到 Vue3。对于鸿蒙 Next（HarmonyOS NEXT），由于其完全脱离安卓生态，采用纯鸿蒙内核（OpenHarmony），UniApp 的兼容性仍在逐步适配中，计划通过编译器将 Vue 代码转换为鸿蒙的 ArkTS 语言。

本文详细讲解基于 UniApp Vue3 开发鸿蒙 App 的完整流程，包括环境配置、证书与签名生成、模拟器调试、打包发布等核心环节，适配 HarmonyOS 4.x+ 版本，UniApp 版本建议 ≥ 3.0。

一、前置环境准备

1. 核心工具安装

• DevEco Studio：鸿蒙官方开发工具，必装。
• Node.js (≥16.x)：UniApp 编译依赖，但 Node.js 12 也可临时使用。
• HBuilderX (≥4.0)：UniApp 开发 IDE，需安装鸿蒙插件。
• JDK 11：DevEco Studio 运行依赖，通常内置，也可手动安装 OpenJDK 11。
• 鸿蒙系统真机版本：确保目标鸿蒙系统的 API 级别为 12 或以上。
• Windows 系统额外设置：若使用模拟器，需在控制面板中启用“Hyper-V”、“Windows 虚拟机监控程序平台”以及“虚拟机平台”。注意，这些功能仅在 Windows 10/11 的专业版或企业版中可用，家庭版用户需先升级。

2. 配置鸿蒙离线 SDK

为了避免多个 UniApp 项目编译到鸿蒙系统时冲突，建议为每个项目准备独立的 SDK 副本。从指定地址下载 UniApp 鸿蒙离线 SDK（如 template-1.3.4.tgz），解压后重命名为当前项目名称，并放置在专门文件夹中（如 D:\Backup\Documents\HBuilderProjects\uniharmonysdk）。然后，使用 DevEco Studio 打开重命名后的 SDK 模板工程进行后续配置。

3. HBuilderX 鸿蒙插件安装

打开 HBuilderX，进入顶部菜单栏的「工具」→「插件安装」，搜索“HarmonyOS”并安装「UniApp 鸿蒙平台编译插件」和「DevEco Studio 集成插件」。

4. DevEco Studio 配置

首次打开 DevEco Studio 后，进入「文件」→「设置」→「OpenHarmony SDK 路径」，下载 HarmonyOS SDK（至少勾选 4.0 及以上版本）。为优化编译路径，可配置环境变量：Windows 系统新增变量 HARMONY_SDK_HOME，指向 SDK 路径（如 C:\Users\用户名\AppData\Local\Huawei\Sdk\HarmonyOS）；Mac 系统编辑 ~/.bash_profile 添加相应路径。

二、鸿蒙证书与签名生成（关键步骤）

鸿蒙 App 的调试和打包必须配置签名证书，分为调试证书和发布证书。

1. 注册鸿蒙开发者账号

访问鸿蒙开发者联盟，注册并完成实名认证（个人或企业）。登录后进入「管理中心」→「证书管理」，完善开发者信息。

2. 生成密钥库（KeyStore）

推荐使用 DevEco Studio 可视化生成：打开 DevEco Studio，进入「构建」→「生成私钥和证书请求文件」，填写密钥库信息：

• KeyStore Path：选择保存路径（如 harmony_key.p12）。
• Password/Confirm Password：设置并确认密钥库密码。
• Alias：密钥别名（如 uniapp_harmony）。
• Password/Confirm Password：别名密码（建议与密钥库密码一致）。
• 其他信息（国家、组织等）按真实情况填写。

点击「Generate」后，生成 .p12 密钥库文件和 .csr 证书请求文件。备用方法是通过命令行使用 keytool 生成 jks 文件。

3. 申请调试或发布证书

回到鸿蒙开发者联盟的「证书管理」，选择「新增证书」，上传生成的 .csr 文件，提交后下载证书文件（.cer）。注意证书有效期，需在失效前更新。

4. 生成 Profile 文件（应用配置文件）

在开发者联盟的「应用管理」中新增应用，填写 App 名称、包名等（包名需与 UniApp 配置一致）。进入应用详情→「Profile 管理」→「新增 Profile」，选择调试或发布类型，关联对应证书，提交后下载 Profile 文件（.p7b）。

5. 配置签名到 DevEco Studio

打开 DevEco Studio，进入「文件」→「项目结构」→「Modules」→选择项目→「Signing Configs」。勾选「Enable Signing」，填写密钥库路径、密码、别名等信息，点击「OK」保存。若遇到 HVIGOR_USER_HOME 路径包含空格导致构建失败，需修改环境变量，将路径设置为无空格、无中文的文件夹（如 D:\huawei\hvigor），然后以管理员身份重启 DevEco Studio。

三、UniApp Vue3 项目适配鸿蒙

1. 项目创建与配置

在 HBuilderX 中创建 UniApp 项目，确保 manifest.json 中的包名与鸿蒙应用配置一致。对于鸿蒙平台，可通过条件编译处理特有代码。

2. 鸿蒙特有 API 适配（可选）

UniApp 已封装大部分跨平台 API，如需调用鸿蒙原生能力，可参考 UniApp 鸿蒙文档或开发原生插件。示例：调用鸿蒙原生 Toast（Vue3 语法）：

<template>
  <button @click="showHarmonyToast">鸿蒙原生Toast</button>
</template>

<script setup>
import { ref } from 'vue'
// #ifdef HARMONYOS
import { prompt } from '@kit.ArkUI'
// #endif

const showHarmonyToast = () => {
  // #ifdef HARMONYOS
  prompt.showToast({
    message: '鸿蒙原生提示',
    duration: 2000
  })
  // #endif
  // #ifndef HARMONYOS
  uni.showToast({
    title: '跨平台提示',
    icon: 'none'
  })
  // #endif
}
</script>

四、开启鸿蒙模拟器并调试

1. 模拟器安装与启动

打开 DevEco Studio，进入「Tools」→「Device Manager」，点击「Phone」→「Create Device」，选择鸿蒙模拟器型号和系统版本（4.0+），下载镜像后启动。首次启动可能较慢，确保电脑虚拟化功能已开启。

2. UniApp 项目运行到模拟器

在 HBuilderX 中打开项目，进入「运行」→「运行到手机或模拟器」→选择「HarmonyOS 模拟器」。HBuilderX 会自动编译并安装应用到模拟器。若编译失败，检查包名一致性、签名配置和 SDK 版本，或尝试以管理员身份重启工具。

五、常见问题解决

1. 模拟器启动失败

可能原因包括电脑未开启虚拟化（VT-x/AMD-V）、Hyper-V 未关闭（Windows）或端口被占用。解决：进入 BIOS 开启虚拟化；Windows 用户关闭 Hyper-V（控制面板→程序→启用或关闭 Windows 功能）；以管理员身份重启 DevEco Studio 和模拟器。

2. 签名失败（Signature verification failed）

可能由于证书过期、包名不匹配或密钥库密码错误。解决：检查开发者联盟中的证书有效性；确认 manifest.json 包名与鸿蒙应用一致；重新配置 DevEco Studio 的签名信息。

3. UniApp 编译鸿蒙项目报错

通常因 HBuilderX 鸿蒙插件版本过低或 SDK 路径配置错误。解决：更新 HBuilderX 和鸿蒙插件至最新版本；检查 HARMONY_SDK_HOME 环境变量是否正确。

六、打包发布鸿蒙 App

1. 版本设置

在 UniApp 基础配置中设置应用版本名称（如 1.0.0.251126）和版本号（如 100，需纯数字且递增），确保与 DevEco Studio 工程中的 app.json5 文件同步，避免冲突。

2. 打包流程

• 通过 HBuilderX：进入「发行」→「鸿蒙 App 打包」，选择发布包，关联发布证书和 Profile 文件，生成安装包（.app 或 .hap 文件）。
• 通过 DevEco Studio：先使用 HBuilderX 生成本地打包资源，替换到 DevEco 工程的相应目录（如 entry/src/main/resources/rawfile/），然后在 DevEco Studio 中配置发布签名，进入「构建」→「编译 Hap(s)/App(s)」生成发布包。

3. 发布到应用市场

登录鸿蒙开发者联盟，上传安装包进行审核，通过后发布到鸿蒙应用市场。建议在证书失效前 1-2 个月提前申请新证书，确保应用正常迭代。

总结

核心流程为：环境配置 → 证书与签名生成 → UniApp 适配 → 模拟器调试 → 打包发布。关键注意点包括包名一致性、签名配置正确性和 SDK 版本匹配。UniApp Vue3 开发鸿蒙 App 已高度封装，大部分跨平台代码无需修改，重点关注鸿蒙特有能力的适配和签名配置即可。

官方参考资料：

• UniApp 鸿蒙配置文档
• 鸿蒙开发者官方文档