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

1、打开 DevEco Studio →「文件/File」→「项目结构/Project Structure」→「Modules」→ 选择项目 →「Signing Configs」。打开 HBuilderX → 顶部菜单栏「工具」→「插件安装」→ 搜索「HarmonyOS」→ 安装「UniApp 鸿蒙平台编译插件」和「DevEco Studio 集成插件」。配置鸿蒙离线SDK，下载并配置uni-ap

avoidaily

633人浏览 · 2025-11-26 17:20:56

avoidaily · 2025-11-26 17:20:56 发布

UniApp是否支持鸿蒙？

UniApp目前支持在鸿蒙系统（HarmonyOS）上进行应用开发，但其支持情况取决于具体的鸿蒙版本和开发需求。

从HBuilderX 4.27版本开始，UniApp支持将Vue3项目编译到鸿蒙平台（Harmony
Next）。开发者可以通过UniApp框架快速开发适配鸿蒙系统的应用。然而，Vue2项目需要先迁移到Vue3才能支持鸿蒙。

对于鸿蒙Next（HarmonyOS
NEXT），由于其完全脱离安卓生态，采用纯鸿蒙内核（OpenHarmony），UniApp的兼容性仍在逐步适配中。目前，UniApp团队计划通过编译器将Vue代码转换为鸿蒙的ArkTS语言，以生成标准的鸿蒙应用工程。

开发鸿蒙应用的步骤

1、环境准备：需要安装DevEco Studio（版本5.0.3.400以上）和HBuilderX（4.22以上），并确保目标鸿蒙系统的API级别为12或以上。

2、配置离线SDK：下载并配置UniApp提供的鸿蒙离线SDK，用于编译项目到鸿蒙系统。

3、项目创建与运行：在HBuilderX中创建UniApp项目，配置鸿蒙SDK路径，并通过DevEco Studio运行和测试。

临时适配方案

对于鸿蒙Next，开发者可以采用以下过渡方案：

· H5模式：将UniApp项目编译为H5，通过鸿蒙的WebView组件嵌入到原生应用中。

· 混合开发：通过鸿蒙的JavaScript Native API调用UniApp的JS逻辑。

注意事项

鸿蒙系统的API设计与安卓不同，开发者需要参考鸿蒙官方文档进行代码改造和UI调整。此外，鸿蒙Next的生态尚不完善，需评估第三方库的兼容性。

总之，UniApp对鸿蒙的支持正在逐步完善，开发者可以根据需求选择适配方案，同时关注UniApp官方和鸿蒙社区的最新动态。

了解详细信息：
1 - uniapp.dcloud.net.cn
2 - developer.huawei.com
3 - blog.csdn.net

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

一、前置环境准备
1、核心工具安装

DevEco Studio，鸿蒙官方开发工具（必装）
Node.js (≥16.x)，UniApp 编译依赖（我的是12，暂时没发现有问题）
HBuilderX (≥4.0)，UniApp 开发IDE（需安装鸿蒙插件）
JDK 11，DevEco Studio 运行依赖，DevEco Studio 内置，也可手动安装 OpenJDK 11
鸿蒙系统真机版本：确保目标鸿蒙系统的API级别为12或以上。
Windows系统额外设置：若使用模拟器，需开启特定功能。打开“控制面板” -> “程序与功能” -> 启用勾选【“Hyper-V”】、【“Windows 虚拟机监控程序平台”】以及【“虚拟机平台”】
注意：这些功能仅在Windows 10/11的专业版或企业版中可用。家庭版用户需先升级。
配置鸿蒙离线SDK，下载并配置uni-app提供的鸿蒙离线SDK，以便在多个uni-app项目中编译到鸿蒙系统，同时避免冲突。
下载SDK：
从指定地址下载uni-app鸿蒙离线SDK，版本为template-1.3.4.tgz。
解压SDK：
解压下载的template-1.3.4.tgz压缩包。
注意：若计划将多个uni-app项目编译到鸿蒙系统，应为每个项目准备一份SDK副本，以避免冲突。鸿蒙设备目前不支持基座概念。
组织SDK文件：
创建一个专门用于存放离线SDK的文件夹，例如D:\Backup\Documents\HBuilderProjects\uniharmonysdk。
将解压后的package重命名为当前uni-app项目的名称，以便区分和管理。

在DevEco-Studio中打开SDK模板工程：
使用DevEco-Studio打开已重命名的SDK模板工程。

2. HBuilderX 鸿蒙插件安装
打开 HBuilderX → 顶部菜单栏「工具」→「插件安装」→ 搜索「HarmonyOS」→ 安装「UniApp 鸿蒙平台编译插件」和「DevEco Studio 集成插件」。

3. DevEco Studio 配置
安装后首次打开 DevEco Studio，文件–设置–OpenHarmony SDK 路径，下载 HarmonyOS SDK（至少勾选 4.0 及以上版本）。
在这里插入图片描述
配置环境变量（可选，解决编译路径问题）：

Windows：新增系统变量 HARMONY_SDK_HOME，值为 DevEco SDK 路径（如C:\Users\用户名\AppData\Local\Huawei\Sdk\HarmonyOS）。
Mac：编辑 ~/.bash_profile，添加 export HARMONY_SDK_HOME=/Users/用户名/Library/Huawei/Sdk/HarmonyOS。

二、鸿蒙证书 / 签名生成（关键步骤）
鸿蒙 App 调试 / 打包必须配置签名证书，分为「调试证书」和「发布证书」，以下是完整流程：
1. 注册鸿蒙开发者账号

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

2. 生成密钥库（KeyStore）

方式 1：DevEco Studio 可视化生成（推荐）

1、打开 DevEco Studio → 顶部菜单栏「构建/Build」→「生成私钥和证书请求文件/Generate Key and CSR」。
2、填写密钥库信息：

KeyStore Path：选择保存路径（如 harmony_key.p12）。
Password/Confirm Password：设置密钥库密码（记住，后续需用）。
Alias：密钥别名（如 uniapp_harmony）。
Password/Confirm Password：别名密码（建议和密钥库密码一致）。
其他信息（国家、组织等）：个人开发者填真实信息，企业填企业信息。
3、点击「Generate」，生成 .jks 密钥库文件和 .csr 证书请求文件。

[DevEco Studio 生成密钥和 CSR 的弹窗]
在这里插入图片描述
1. Key store file（.p12）：【密钥库文件】是DevEco自动生成的，无需手动新建。选择保存路径，在下方输入框填入文件名例如harmony_key.p12即可。
作用：这是存储密钥信息的文件（鸿蒙用.p12格式，.jks是 Java 常用格式）。
操作：点击New按钮（不要选Choose Existing，因为你是首次生成），然后选择一个保存路径（比如桌面），给文件命名（例如harmony_key.p12），点击确定即可。

2. Key store password：密钥库密码
作用：保护整个密钥库的密码，后续配置签名时需要用到。
要求：长度至少 8 位，包含大小写字母、数字、特殊符号（比如Abc123!@#）。输入后要记住这个密码，别丢了！

3. Key 部分（密钥信息）
Alias：密钥别名。给这个密钥起个名字（比如uniapp_harmony），方便后续识别。
Password：密钥密码。建议和 “密钥库密码” 保持一致（减少记忆负担），要求同密钥库密码。

4. Advanced Setting（高级设置，可选）
点击展开后，默认选项（密钥算法 RSA、密钥长度 2048、有效期 3650 天）不用改，保持默认即可。
填完这些信息后，点击Next，就能生成密钥库文件（.p12）和 CSR 文件啦～
![在这里插入图片描述](https://i-blog.csdnimg.cn/direct/4ee38f7b75034f24ab5b75d107b1bad1.png
1、点击CSR file (*.csr)右边的文件夹图标；
2、选择保存路径（比如和 p12 文件存在同一个位置，比如桌面）；
3、给 CSR 文件起个名字（比如yxapp_harmony.csr），点击 “确认”。
4、填好 CSR 文件路径后，再点击Finish，就能同时生成p12 密钥库文件和csr 证书请求文件啦～

方式 2：命令行生成（备用）

# JDK 11 环境下执行，生成 jks 密钥库
keytool -genkeypair -alias uniapp_harmony -keyalg RSA -keysize 2048 -validity 3650 -keystore harmony_key.jks

按提示输入密码、个人信息，完成生成。

3. 申请调试 / 发布证书（注意证书失效日期）
回到鸿蒙开发者联盟「证书管理/证书、APP ID和Profile」→「新增证书」：

选择「调试证书」（开发阶段用）或「发布证书」（上架用）。
上传步骤 2 生成的 .csr 文件，提交后下载证书文件（.cer）。

4、生成 Profile 文件（应用配置文件）（注意证书失效日期）
开发者联盟「应用管理」→ 新增应用（填写 App 名称、包名等，包名需和 UniApp 配置一致）。
在这里插入图片描述

进入应用详情 →「Profile 管理」→「新增 Profile」：
选择「调试 Profile」（关联调试证书）或「发布 Profile」（关联发布证书）。
提交后下载 Profile 文件（.p7b）。
在这里插入图片描述
5. 配置签名到 DevEco Studio
1、打开 DevEco Studio →「文件/File」→「项目结构/Project Structure」→「Modules」→ 选择项目 →「Signing Configs」。

2、勾选「Enable Signing」，填写：
KeyStore Path：选择步骤 2 生成的 .jks 文件。
KeyStore Password：密钥库密码。
Key Alias：密钥别名。
Key Password：别名密码。
3、点击「OK」保存，DevEco 会自动关联证书和 Profile。
在这里插入图片描述
点击【ok】，若下图的报错信息，表示构建失败的错误信息，核心问题是：HVIGOR_USER_HOME路径包含空格，导致 pnpm 安装依赖失败。
解决方法：

关闭 DevEco Studio；
找到系统环境变量，新增/修改用户变量 HVIGOR_USER_HOME：
路径选择无空格、无中文的文件夹（比如D:\huawei\hvigor）；
[以管理员身份]重启 DevEco Studio，重新打开项目，等待依赖重新安装。重新执行【文件】–【项目结构】–【Projeck】–【Signing Configs】–【ok】

三、UniApp Vue3 项目适配鸿蒙

项目基础配置
1、打开 HBuilderX，新建 / 打开 UniApp Vue3 项目。
2、修改 manifest.json 配置：
「基础配置」→ 包名（Bundle ID）：需和鸿蒙开发者联盟申请的应用包名一致。
「鸿蒙配置」→ 勾选「HarmonyOS 平台」，填写：
SDK 版本：选择已安装的 HarmonyOS SDK 版本（如 4.0）。
签名配置：关联 DevEco Studio 配置的签名信息（HBuilderX 会自动读取 DevEco 配置）。

2、鸿蒙特有 API 适配（可选）
UniApp 已封装大部分跨平台 API，若需调用鸿蒙原生能力，可通过：

UniApp 鸿蒙扩展 API：参考 UniApp 鸿蒙文档。
原生插件开发：通过 DevEco Studio 开发鸿蒙原生插件，导入 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」，选择鸿蒙模拟器型号（如 Phone 9.0 英寸）、系统版本（4.0+）。
点击「Finish」，等待模拟器镜像下载完成（需联网，约几分钟）。
在这里插入图片描述

2. 启动模拟器
在 Device Manager 中，选择已创建的模拟器 → 点击「Launch」，等待模拟器启动（首次启动较慢）。
模拟器启动后，可在 DevEco Studio 右下角看到设备状态（在线）。

3. UniApp 项目运行到模拟器
1、回到 HBuilderX，打开 UniApp 项目 → 顶部菜单栏「运行」→「运行到手机或模拟器」→ 选择「HarmonyOS 模拟器」。
在这里插入图片描述

2、HBuilderX 会自动编译项目，并将 App 安装到鸿蒙模拟器中：
编译过程中会自动关联签名配置，无需手动操作。
若编译失败，检查：包名是否一致、签名配置是否正确、SDK 版本是否匹配。可以尝试「以管理员身份运行」重启工具。
成功后，模拟器中会显示 UniApp 应用，可实时调试。

五、常见问题解决

1. 模拟器启动失败

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

2. 签名失败（Signature verification failed）

原因：证书 / Profile 过期、包名不匹配、密钥库密码错误。
解决：
检查开发者联盟的证书是否有效。
确认 manifest.json 包名和鸿蒙应用包名一致。
重新配置 DevEco 的签名信息。

3. UniApp 编译鸿蒙项目报错

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

六、打包发布鸿蒙 App
1、在 HBuilderX 中，点击「发行」→「鸿蒙 App 打包」。
2、选择「发布包」，关联发布证书和 Profile 文件。
3、点击「打包」，生成鸿蒙 App 安装包（.app 或 .hap 文件）。
4、登录鸿蒙开发者联盟，上传安装包进行审核，审核通过后发布到鸿蒙应用市场。
补充：建议在证书失效前 1-2 个月提前申请新证书，重新配置即可，避免影响应用的正常迭代或上架。

版本设置，uni和DevEco需一致
在这里插入图片描述
1、应用版本名称（如1.0.0.251126）：是展示给用户的版本标识；
2、应用版本号（如100）：是鸿蒙应用市场审核时的版本区分标识（需为纯数字，且每次发布必须递增，100 -> 101）。
3、注意事项：
uniapp基础配置设置的版本，会被打包到 UniApp 生成的鸿蒙资源中，最终同步到 DevEco Studio 工程的配置文件里；
若后续在 DevEco Studio 中修改版本，需确保与这里的配置一致，避免版本冲突。

在这里插入图片描述

//修改文件：\SDK\yongxin-IM-HM\entry\oh-package.json5（不用改）
修改文件：\SDK\yongxin-IM-HM\AppScope\app.json5
versionName：1.0.0.251126 是展示给用户的版本标识，
versionCode：100 是应用市场的版本区分标识（需递增）；
这两个字段是鸿蒙工程打包时的版本依据，必须与 UniApp 配置完全同步，否则会导致版本不匹配。

两种发布流程：

一、【HBuilder X】（需配置好与鸿蒙开发者联盟一致的发布证书）

HBuilder X — 发行 — 生成安装包 —
E:\yongxin_project\yongxin-IM-HM\unpackage\dist\build\app-harmony\build\outputs\release\app-harmony-release-signed

二、【DevEco】

HBuilder X — 发行 — App Harmony本地打包 — 生成本地打包App资源 —

1.1、（处理__UNI__84FDAC6资源）\unpackage\resources__UNI__84FDAC6\www — 替换到 DevEco Studio 6.0工程的
D:\huawei\SDK\yongxin-IM-HM\entry\src\main\resources\rawfile\apps\HBuilder\www

1.2、（处理uni_modules资源）\unpackage\resources\uni_modules — 替换到 DevEco Studio 6.0工程的
D:\huawei\SDK\yongxin-IM-HM\entry\src\main\resources\rawfile\目录下（与apps文件夹同级）。

DevEco Studio — 文件 — 项目结构 — Project — Singing Confiig — release（发布模式，配置的是发布证书） —OK
顶部菜单：构建 — 编译Hap(s)/App(s) — 调试包-hap || 发布包-app
安装包地址：D:\huawei\SDK\yongxin-IM-HM\build\outputs\default\yongxin-IM-HM-default-signed.app

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

官方资料：官方配置调试签名 —> 官方申请发布证书