为什么是 uni-app + Harmony Next？

很多人第一次听到“uni-app 开发鸿蒙”时，第一反应是：为什么不用官方 ArkTS 直接写？
确实，如果只做一个纯鸿蒙应用，用 DevEco Studio + ArkTS 是最直接的方式。但如果你需要同时维护 Android、iOS、Web 和鸿蒙多个平台，而团队已经积累了一套 Vue 技术栈的代码，那么 uni-app 的跨平台能力就变成了刚需。

官方文档提到，从 HBuilderX 4.27 开始支持 uni-app 编译到 Harmony Next（这里简称 Harmony Next）。目前仅支持 Vue 3 项目。这意味着你可以在同一个工程里，一套代码同时发布到 iOS、Android、Web、以及 HarmonyOS Next 应用市场。

适合的场景：

• 已有的 uni-app 项目需要新增鸿蒙平台
• 团队以 Vue 技术栈为主，不愿再投入 ArkTS 学习成本
• 项目对原生能力依赖不深，更多是 UI 和数据交互

不适合的场景：

• 需要深度调用鸿蒙原生 API（如分布式流转、元服务卡片）
• 对性能要求极高，且需要极致优化渲染的复杂动画
• 业务逻辑与 ArkTS 语言特性（如并发 TaskPool）紧密耦合

环境准备

工具	版本要求	备注
HBuilderX	4.27 及以上	从官网下载正式版
Node.js	16+ (推荐 18+)	用于 uni-app 构建
鸿蒙模拟器	HarmonyOS NEXT 模拟器	需要 DevEco Studio 侧载或使用华为云模拟器

注意：HBuilderX 4.27 是首个支持鸿蒙编译的版本，低于此版本无法看到鸿蒙运行选项。模拟器推荐使用华为 DevEco Studio 自带的 Local Emulator，或者直接连接真机（需要注册华为开发者账号并获取证书）。

第一步：安装 HBuilderX 并创建项目

1. 访问 DCloud 官网下载 HBuilderX 4.27+。
2. 安装后打开，点击“新建项目” → “uni-app”。

关键配置：

• 项目类型：默认 uni-app
• 模板：选择 默认模板（Vue3）
• 版本：选择 Vue3（Vue2 项目不能编译到鸿蒙）

创建完成后，项目目录结构如下：

my-app/
├── pages/           # 页面文件
│   └── index/       # 首页
│       └── index.vue
├── static/          # 静态资源
├── manifest.json    # 应用配置（关键）
├── pages.json       # 路由和页面配置
├── uni.scss         # 全局样式
└── main.js          # 入口

第二步：检查关键配置文件

manifest.json（鸿蒙特有字段）

打开 manifest.json，切换到“源码视图”，你会看到类似结构。鸿蒙编译需要增加 harmony 字段（HBuilderX 4.27 会自动生成基础配置）：

{
  "name": "my-app",
  "appid": "__UNI__XXXXXXX",
  "versionName": "1.0.0",
  "versionCode": "100",
  "harmony": {
    "packageName": "com.example.myapp",
    "versionName": "1.0.0",
    "versionCode": 1,
    "minSdkVersion": 23,
    "targetSdkVersion": 23,
    "icon": "/static/logo.png",
    "label": "我的应用"
  },
  "app-plus": {
    // ... 其他平台配置
  }
}

注意：minSdkVersion 对应 HarmonyOS NEXT 的 API 等级（23 代表 NEXT 版本）。如果使用地图、定位等模块，还需要在此处配置腾讯地图 key，但本文暂不涉及。

pages.json（路由配置）

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页"
      }
    }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "uni-app",
    "navigationBarBackgroundColor": "#F8F8F8",
    "backgroundColor": "#F8F8F8"
  }
}

鸿蒙平台的路由渲染完全遵循 uni-app 标准，无需额外处理。

第三步：编译到鸿蒙模拟器

1. 确保你已经安装并启动了鸿蒙模拟器（推荐使用 DevEco Studio 内置 Local Emulator，系统镜像为 HarmonyOS NEXT）。
2. 在 HBuilderX 顶部工具栏，点击“运行”下拉菜单，选择 “运行到鸿蒙模拟器”。

首次运行需要配置模拟器连接地址（一般是 127.0.0.1:5555），HBuilderX 会自动扫描。点击确定后开始编译，会生成一个 unpackage/debug/harmony 目录，其中包含标准的 HarmonyOS NEXT 工程结构（ets、resources 等）。

编译完成后，模拟器会自动安装并启动应用。你会看到模拟器屏幕上显示 uni-app 默认的 Hello 页面。

常见问题与踩坑

问题1：编译报错“请确认HBuilderX版本 >= 4.27”

现象：点击运行后 HBuilderX 提示版本过低。
原因：部分开发者下载了 4.26 及以下版本，或者使用了绿色版未更新。
解法：前往官网重新下载最新版，不要使用插件市场内的“升级”。检查 HBuilderX 菜单 → 关于 → 版本号。

问题2：模拟器连接失败，提示“未找到 HarmonyOS 设备”

现象：运行菜单中“运行到鸿蒙模拟器”是灰色，或者点击后无法继续。
原因：一是未启动模拟器，二是 HBuilderX 无法自动识别 adb 端口。
解法：

• 确保 DevEco Studio 的 Local Emulator 已启动且处于“running”状态。
• 在 HBuilderX 中手动配置 adb 路径：菜单 → 设置 → 运行配置 → HarmonyOS 模拟器 adb 路径，填写 DevEco Studio 自带的 hdc 工具（通常位于 %DEVECO_HOME%/sdk/default/hms/toolchains/hdc.exe）。
• 有些情况需要将模拟器切换到“调试模式”（Settings → Developer options → USB debugging 开启）。

问题3：页面显示空白，控制台无错误

现象：模拟器成功安装应用，但屏幕上只有白色背景。
原因：渲染引擎未正确加载，常见于项目使用了不兼容的 Vue 3 语法（如 <script setup> 在部分早期版本支持不完整）。
解法：降级使用 export default { setup() {} } 方式。检查 main.js 中是否正确引入了 App.vue 并挂载。

最佳实践（面向初学者）

1. 优先使用 Vue3 选项式 API
   组合式 API（<script setup>）在 HBuilderX 4.27 编译时偶发缓存问题，建议初期用选项式 API 规避。等后续稳定后再切换。

2. 避免在 manifest.json 中直接修改鸿蒙原生配置
   除非你十分熟悉 HarmonyOS 的 module.json 结构，否则建议在 HBuilderX 的可视化编辑器中操作（“App 模块配置” → “HarmonyOS 配置”）。手动修改可能导致编译失败。

3. 真机调试比模拟器更可靠
   模拟器虽然方便，但部分原生能力（如定位、NFC）在模拟器中无法测试。且模拟器内存有限，运行复杂页面容易卡顿。建议尽早连接真机（需要注册华为开发者账号并申请签名证书）。

FAQ

Q：为什么只能创建 Vue3 项目？Vue2 什么时候支持？
A：官方目前仅宣布 Vue3 支持，Vue2 需要先迁移到 Vue3。本质上是因为 Vue2 的响应式系统在鸿蒙的渲染引擎上存在兼容性问题，短期内不会开放。

Q：HBuilderX 4.27 是否自带鸿蒙 SDK？
A：不包含。编译时 HBuilderX 会调用你电脑上已安装的 DevEco Studio 的 SDK。你需要在 DevEco Studio 中自行下载 HarmonyOS NEXT 的 SDK 和模拟器镜像。

Q：现有 uni-app 项目直接运行到鸿蒙，需要修改大量代码吗？
A：取决于你对原生 API 的依赖程度。如果是纯 UI 项目，基本零修改。如果使用了 plus.* 或 uni 原生模块（如地图、支付），需要检查对应模块在鸿蒙下的支持情况（官方文档有“内置模块说明”）。建议先在空项目上验证核心功能。

---