展示全部

# 运行和发行

HBuilderX 版本需 ≥ 4.24

uni-app鸿蒙化技术交流群

# 兼容性说明

鸿蒙开发只支持Vue3，不支持Vue2、不支持plus、但支持nvue
nvue编译到鸿蒙后非原生渲染，而是与web一样渲染（自动注入一些默认样式进行兼容）
Vue3也支持选项式代码风格，参考Vue2升Vue3指南

# 开发环境要求

HBuilderX 4.24+ 下载地址
DevEco-Studio 下载地址
- HBuilderX 4.24+ 要求 DevEco-Studio 5.0.3.400+，HBuilderX 4.31+ 要求 DevEco-Studio 5.0.3.800+。
- 鸿蒙系统版本 API 12 以上（DevEco-Studio有内置鸿蒙模拟器）
HBuilderX 4.31+ 构建的鸿蒙运行包不支持 x86_64 平台，会影响到 Windows 系统和部分 Mac 系统的鸿蒙模拟器无法使用，需使用真机调试

Windows系统如使用模拟器则需要开启以下功能

打开控制面板 - 程序与功能 - 开启以下功能

Hyper-V
Windows 虚拟机监控程序平台
虚拟机平台

注意: 需要win10专业版或win11专业版才能开启以上功能，家庭版需先升级成专业版或企业版

# 调试运行的方式

HBuilderX 4.24 版本开始支持【运行到鸿蒙】，具体的方式是又开发者下载鸿蒙工程模板并创建独立的鸿蒙工程目录，然后在 uni-app 项目中的 manifest.json 里面设置 app-harmony.projectPath 属性来指向这个鸿蒙工程目录， uni-app 项目在编译时把编译产物输出到鸿蒙工程目录，然后调起 DevEco Studio 打开鸿蒙工程目录，由开发者手动完成后续的运行调试工作。

HBuilderX 4.27+ 开始已经把鸿蒙工程模板内置到 HBuilderX 中，【运行到鸿蒙】时自动创建鸿蒙工程目录，与 uni-app 项目的编译产物合并，然后调用鸿蒙工具链完成打包和安装、运行等操作，同时从运行设备上收集输出的日志显示到 HBuilderX 的控制台。

新的内置模板的方式虽然在调试运行过程中不再调起 DevEco Studio，但一般来说仍然需要安装 DevEco Studio，因为：

需要使用 DevEco Studio 提供的鸿蒙工具链来完成相关操作。
启动鸿蒙模拟器这个操作只能在 DevEco Studio 中完成。
调试运行时如果需要进行数字签名，可以在 DevEco Studio 中自动申请调试证书。

# 启动鸿蒙模拟器

在 DevEco Studio 中打开任意一个项目（也可以新建一个空项目），然后在下图的位置进入设备管理器：

如果没有登录华为账号，此时需要先登录，登录成功后看到如下页面

选择模拟器型号，选第一个即可

安装完模拟器后，点击启动按钮启动模拟器

# 连接鸿蒙真机

注意：真机需要鸿蒙系统版本 API 12 以上

打开鸿蒙手机开发者模式，开启USB调试，通过USB线连接电脑，在此处能看到对应的设备标识符则表示连接成功

# 证书签名配置指南

注意：配置签名需要先启动模拟器或连接真机后才能配置

点击 DevEco-Studio 上方菜单 File - Project Structure...

生成运行调试证书和签名

在弹出的窗体中选择 Project - Signing Configs，并打钩 Automatically generate signature，即可自动生成签名

使用发布证书生成发布用的签名

需要先申请发布证书

在弹出的窗体中选择 Project - Signing Configs，并手动填写证书信息和密钥

依次点击 Apply 和 OK 使签名生效

如果是运行证书还是发布证书，生成的签名在文件 build-profile.json5 内

将它复制到你的 uni-app 项目根目录的 harmony-configs/build-profile.json5 的 signingConfigs 配置中

# 配置 HBuilderX settings.json

打开HBuilderX，点击上方菜单 - 工具 - 设置，再点击运行配置，在鸿蒙运行配置中设置 DevEco Studio 的路径

# 运行uniapp项目到鸿蒙

HBuilderX 新建一个空白的 uni-app 项目，选vue3（也可使用已有的uni-app vue3项目）
编译 uni-app 到鸿蒙

点击 HBuilderX 上方【运行】菜单 - 运行到手机或模拟器 - 运行到鸿蒙

【首次运行】此时如果是第一次运行本项目会在项目根目录下生成harmony-configs目录用于存放鸿蒙配置文件

【首次运行】配置签名信息、包名到鸿蒙配置文件内

参考：修改鸿蒙工程配置

再次运行项目，选择目标设备

# 发行鸿蒙应用到应用市场

使用hbx（4.28以上），点击【发行】- 【App-Harmony-本地打包】

项目第一次发行时，会出现如下提示

配置签名
配置完签名后，再次点击【发行】- 【App-Harmony-本地打包】即可得到已签名的 .app 安装包文件
最后还需参考鸿蒙官方文档发布鸿蒙应用到应用市场，详见文档

# 权限配置指南

部分API需要在配置文件显示声明权限才能调用，权限的配置文件路径为：/harmony-configs/entry/src/main/module.json5，配置节点为：requestPermissions，如下图所示

具体请查看以下文档

# 更多配置指南

项目的根目录下有一个 harmony-configs 目录，每当执行跟鸿蒙相关的操作时，HX 都会检查这个目录，如果目录不存在则会自动创建。该目录中初始会存在几个常用的配置文件。

在执行运行或者发行到鸿蒙的操作过程中，HX 会根据内置模板生成一个鸿蒙工程目录（一般在 unpackage 目录下游），然后把 harmony-configs 目录下的所有内容都原样覆盖过去，然后再调用鸿蒙的工具链进行编译打包等操作。

所以，harmony-configs 目录中的所有文件最终都会原样进入鸿蒙工程目录参与项目构建，所有需要对鸿蒙工程的定制化配置都可以写在这个目录下（注意：在 manifest.json 的【鸿蒙配置】中设置的选项将具有更高的优先级）。

关于 harmony-configs 目录的使用要遵守鸿蒙的技术规范，具体可参考鸿蒙官方文档

# 注意事项

移植已有的 uni-app 项目源码时，如有其他 npm 依赖，请自行安装
现阶段条件编译仅 APP-HARMONY、APP 可以命中鸿蒙平台
每次HBuilderX改动源码后，DevEco-Studio 内需要点重新运行才能生效
如果模拟器白屏了，尝试重启软件 DevEco-Studio，再重启项目
如果模拟器无法连接了，尝试重启电脑
在HBuilderX里运行后，需要再去鸿蒙 DevEco Studio里运行
在HBuilderX里修改代码后，需要去鸿蒙 DevEco Studio里重新运行
如果有多个uni-app项目要编译到鸿蒙，那么鸿蒙离线sdk需要放置多份，每个uni-app的manifest中配置不同的离线sdk地址，否则会冲突，鸿蒙设备上目前没有基座概念

# 常见问题

# 运行失败报错如 `Unexpected token (Note that you need plugins to import files that are not JavaScript)` 或 `Please make sure that the splash page has one and only one '@Entry' decorator`

请将 HBuilderX 项目向上层目录移动，直到运行成功。这是因为鸿蒙在编译 ArkTs 时，.ets 文件路径总长不能大于 255 个字符。

# 如何修改应用名称、图标、权限等信息

参考鸿蒙官方文档：应用/组件级配置

# 应用图标资源规范

为保证图标在系统内显示的一致性，应用预置的图标资源应满足以下要素：

图标资源必须为分层资源（一张前景图和一张背景图）
图标资源尺寸必须为1024*1024px
图标资源必须为为正方形图像，系统会为对应场景自动生成遮罩裁切

# 启动图资源规范

启动页可以配置背景色代码（默认为#FFFFFF）和一张启动图，启动图没有尺寸要求，但建议为正方形logo图

# 如何进行条件编译

仅 APP-HARMONY 和 APP 可以条件编译命中鸿蒙平台，APP-PLUS 不能命中中鸿蒙平台

// #ifdef APP-HARMONY
console.log("仅鸿蒙会编译")
// #endif

// #ifndef APP-HARMONY
console.log("仅非鸿蒙会编译")
// #endif

// #ifdef APP
console.log("安卓、苹果、鸿蒙会编译，小程序和Web不会编译")
// #endif

// #ifndef APP
console.log("安卓、苹果、鸿蒙不会编译，小程序和Web会编译")
// #endif

// #ifdef APP-PLUS
console.log("安卓、苹果会编译，鸿蒙不会编译，小程序和Web也不会编译")
// #endif

// #ifndef APP-PLUS
console.log("安卓、苹果不会编译，鸿蒙会编译，小程序和Web也会编译")
// #endif