新手记录使用uniapp-x开发鸿蒙应用

提示：文章写完后，目录可以自动生成，如何生成可参考右边的帮助文档

---

前言

提示：这里可以添加本文要记录的大概内容：

uniapp官方文档

提示：以下是本篇文章正文内容，下面案例可供参考

一、在HBuilder中新建uniapp-x工程

二、在 HBuilderX 中设置 DevEco Studio 的安装位置

HBuilderX 依赖于 DevEco Studio 里面带的鸿蒙工具链，所以需要电脑已经安装了符合版本要求的 DevEco Studio。

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

三、manifest.json中设置包名

四、在 HBuilderX 运行项目到鸿蒙设备（主要目的是让生成鸿蒙代码unpackage\dist\dev\app-harmony）

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

五、DevEcoStudio中打开生成项目，进行自动签名，然后运行。

至此，可以看到一个uniapp-x生成的鸿蒙应用。

其他

# 在 HBuilderX 里面直接配置证书签名

从 HBuilderX 4.61+ 开始支持这种配置方式。在【运行到鸿蒙】操作的【选择运行设备】对话框中，点击【配置调试证书】按钮，打开配置对话框：

在 manifest.json 的编辑页面中，【鸿蒙 App 配置】里面也有打开配置对话框的按钮，分别用于配置调试证书和发布证书：

配置证书的对话框：

# 证书资料文件

需要设置的文件总共有三个：

如果已经在 AppGallery Connect 中手动申请过证书，则开发者手中应该已经掌握了所有的必备信息（三个文件，两个密码和一个私钥别名），填写到对话框中即完成配置。 其中三个文件的位置如果位于 harmony-configs 目录里面，则会被处理为相对路径。

如果是通过 DevEco Studio 自动申请的调试证书，在 build-profile.json5 文件里能找到完整的证书配置信息。 需注意的是，在保存那三个文件的目录里还应该有一个 material 子目录，它跟私钥库文件（.p12）和两个密码是配合使用的，如果想把私钥库文件移到别的地方去，这个 material 目录也要复制过去（否则密码将失效）。

# 应用包名

自动申请得到的签名描述文件是跟给定的包名绑定的，只能用于对设置了相同包名的项目进行签名。

如果是自己手动申请的签名证书，请注意与这里的包名保持一致，否则在填写了签名描述文件之后会出现提示警告。

# 运行设备

只有在配置调试证书的对话框里有这项内容。当自动申请调试证书的时候，得到的签名描述文件与给定的设备是绑定的，签名后的应用只能运行于这里列出的设备。

如果是自己手动申请的签名证书，请注意签名描述文件里面包含了这里列出的所有设备，否则在填写了签名描述文件之后会出现提示警告。

点击左侧的【检测】按钮会自动检测出当前已经连接的运行设备（真机或者模拟器），并自动填写到文本框里。

填写的内容是设备的唯一标识，可以填写多个，用半角逗号或者换行符分隔。

如果没有填写有效的设备唯一标识，则无法进行自动申请调试证书的操作。

# 密码

私钥库密码和私钥密码需符合一定的要求：须由 6 ~ 64 个字符组成，可包含大小写字母、数字以及如下特殊字符 ~!@#$%^&*()-_=+\|[{}];:\'",<.>/?，首字符不能为连字符（-）。

如果是在 AppGallery Connect 中手动申请的证书，开发者应该知道申请时所使用的密码，直接在这里填写就可以了。

如果是通过 DevEco Studio 自动申请的调试证书，在 build-profile.json5 文件里能找到证书配置信息，其中的密码是加密过的，一般是 76 个或更多的 HEX 字符。 这种加密后的密码也可以直接拿来填写，但需要注意，这种密码要跟前面提到的 material 目录配合使用，否则在签名时将会发生错误。

# 自动申请调试证书

对于调试证书，可以选择自动申请，此时 HBuilderX 会使用开发者授权的账号身份调用 AppGallery Connect 的 API 来自动完成证书的申请和配置。

点击【自动申请】按钮，会触发浏览器打开华为的登录授权页面：

完成登录授权：

回到 HBuilderX 的对话框中，正常情况下完成自动申请之后，点击【保存】按钮保存即可。

如果自动申请过程中出现错误，可根据错误提示信息进行处理：

# 通过 DevEco Studio 获取证书签名配置

HBuilderX 4.61 之前的版本，只能通过 harmony-configs/build-profile.json5 文件来配置签名证书，里面的证书资料信息只能由 DevEco Studio 来生成, 即使是自己在华为 AppGallery Connect 网站上手动申请的证书，也需要填写到 DevEco Studio 里面才能最终得到所需的 build-profile.json5 文件。

DevEco Studio 须先打开一个鸿蒙工程才可进行证书相关的操作，建议先执行一次【运行到鸿蒙】，然后在项目的 unpackage 目录下找到临时生成的鸿蒙工程目录， 在 DevEco Studio 里面打开后再进行后面的操作。 如果是自己在 DevEco Studio 里面独立创建一个新的鸿蒙工程，虽然也可以用于申请证书，但需注意以下几点：

1. 由于证书资料中包含应用的包名，所以在这个鸿蒙工程中设置的应用包名应该与将要开发的 uni-app 应用项目中设置的鸿蒙应用包名（在 manifest.json 中设置）相一致，这样申请到的证书资料才会有效；

2. 这个鸿蒙工程的根目录中的 build-profile.json5 文件中的内容应该与 HBuilderX 自动生成的鸿蒙工程中的对应文件保持一致（随着版本迭代该文件的内容可能会有少许变化），否则在后续操作中可能产生异常。

3. 如果有用到 ACL 权限，需在 entry/src/main/module.json5 中声明，这样获得的证书中才能包含相关的授权。参考 权限配置指南

完成申请证书的操作之后，把这个鸿蒙工程中的 build-profile.json5 文件复制到 uni-app 项目的 harmony-configs/build-profile.json5 即可。

# 打开证书配置对话框

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

# 调试用的数字签名证书

在使用模拟器进行调试运行的时候，一般是不需要做数字签名的，但如果是用真机进行调试运行，或者业务代码用到了 ACL 权限，那么就需要申请并配置一个调试证书用于数字签名。

参考 申请调试证书

在对话框中选择 Project - Signing Configs，并勾选 Automatically generate signature，即可自动生成签名证书资料

参考 自动签名

通过 DevEco Studio 自动申请得到的证书，缺省会保存到电脑的用户目录下，在 Windows 系统中一般是 %USERPROFILE%\.ohos\config，在 Mac 系统中一般是 ~/.ohos/config。 配置信息中包含的三个文件缺省都是采用绝对路径来表示，也可以把这些文件移到 harmony-configs 目录下，这样就可以使用相对路径来表示，相对于 harmony-configs 目录。 如果要移动证书文件的位置，需注意跟这三个文件一起的还有一个名为 material 的目录，也要一起移动。

也可以在对话框中填写手动申请到的证书，填写的时候注意三个文件要在同一个目录。

完成以上操作后，鸿蒙工程中的 build-profile.json5 文件就包含了完整的调试证书配置信息（在 app.signingConfigs 数组里，name 属性的值是 "default"）。

# 发布用的数字签名证书

在发行安装包的时候，一定需要配置一个发布证书，否则只能拿到一个未签名的安装包，是无法实际使用的。

发布证书只能手动申请，申请完成后把拿到的相关资料文件填写到 DevEco Studio 里面，填写的时候注意三个文件要在同一个目录。

参考 申请发布证书

在对话框中选择 Project - Signing Configs，不要勾选 Automatically generate signature，创建一个名为 release 的配置项。

完成以上操作后，鸿蒙工程中的 build-profile.json5 文件就包含了完整的发布证书配置信息（在 app.signingConfigs 数组里，name 属性的值是 "release"）。

# 把生成的证书配置信息拷贝到 uni-app 项目中

无论是调试证书还是发布证书，生成的证书资料信息都在鸿蒙工程根目录下的 build-profile.json5 文件中，把这个文件复制到 uni-app 项目的 harmony-configs/build-profile.json5 即可。

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

1. 使用 HBuilderX 4.28+，点击【发行】-【App-Harmony-本地打包】

   

   如果项目中没有 harmony-configs 目录，此时会自动生成。

2. 如果日志窗口提示没有配置签名证书资料，则去 配置发布证书的资料

3. 配置完证书资料后，再次点击【发行】- 【App-Harmony-本地打包】即可得到已签名的 .app 安装包文件

4. 最后还需参考鸿蒙官方文档发布鸿蒙应用到应用市场，详见文档

# 鸿蒙 App 配置

这里的配置是专用于传递给鸿蒙工程使用。

以上的配置项有可能随着 HBuilderX 的升级而有所增加，其优先级高于后面所述的 harmony-configs 目录。如果这些仍没有满足需求，则可以自行在 harmony-configs 目录中进行配置。

# 使用 harmony-configs 配置目录

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

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

所以，harmony-configs 目录中的所有文件最终都会原样进入鸿蒙工程目录参与项目构建，所有需要对鸿蒙工程的定制化配置都可以写在这个目录下。

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

经常会用到的配置文件有：

# 注意事项

1. 移植已有的 uni-app 项目源码时，如有其他 npm 依赖，请自行安装
2. 现阶段条件编译仅 APP-HARMONY、APP 可以命中鸿蒙平台
3. HBuilderX 4.27 以前的版本，在 HBuilderX 里运行后，需要再去鸿蒙 DevEco Studio 里运行；在 HBuilderX 中改动源码后，需要在 DevEco Studio 内点重新运行才能生效
4. 如果模拟器白屏了，尝试重启软件 DevEco Studio，再重启项目
5. 如果模拟器无法连接了，尝试重启电脑

# 常见问题

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

manifest.json 里面已经支持一些应用配置项，未直接支持的可以通过 harmony-configs 来设置，详情参见 更多配置指南。

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

# 应用图标资源规范

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

# 启动图资源规范

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

# 如何进行条件编译

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