uniapp开发HarmonyOS原生应用完整指南

UniApp 开发 HarmonyOS 原生应用完整指南

---

项目概述

本项目基于 uni-app + Vue3 + TypeScript + Vite5 + UnoCSS 构建，支持 HarmonyOS 原生应用开发。通过 uni-app 框架，可以一套代码多端运行，包括 H5、小程序、Android、iOS 和 HarmonyOS。

HarmonyOS 平台特性

• ✅ 支持 HarmonyOS 原生应用开发
• ✅ 支持 uni-push 推送模块
• ✅ 支持暗黑模式
• ✅ 支持权限管理（相机、麦克风、存储、电话等）
• ✅ 支持应用更新
• ✅ 支持自定义启动页和图标

---

环境要求

基础环境

• Node.js: >= 22.0.0（Windows <= 22.16.0）
• pnpm: >= 10.10.0
• 操作系统: macOS、Windows

HarmonyOS 开发环境

• DevEco Studio: 最新版本（推荐 6.0+）
• HarmonyOS SDK: API 9+（通过 DevEco Studio 安装）不需要安装，了解即可
• HarmonyOS 模拟器: 或真机设备

验证环境

# 检查 Node.js 版本
node -v

# 检查 pnpm 版本
pnpm -v

---

## 项目依赖

### 核心依赖

项目已包含以下 HarmonyOS 相关依赖：

```json
{
  "@dcloudio/uni-app-harmony": "3.0.0-4070620250821001",
  "@dcloudio/uni-mp-harmony": "3.0.0-4070620250821001"
}

安装依赖

# 进入项目目录
cd uniapp-wmall

# 安装项目依赖（使用 pnpm，项目强制使用 pnpm）
pnpm install

注意：项目使用 only-allow pnpm 强制使用 pnpm 作为包管理器，不能使用 npm 或 yarn。

依赖说明

• @dcloudio/uni-app-harmony: uni-app HarmonyOS 平台核心库
• @dcloudio/uni-mp-harmony: uni-app HarmonyOS 元服务

---

项目配置

1. 环境变量配置

使用脚本自动生成（推荐）

# 根据 env-conf.ts 自动生成环境变量文件
pnpm generate-env

这会根据 env-conf.ts 配置文件自动生成以下文件：

• .env.development - 开发环境
• .env.uat - UAT 环境
• .env.production - 生产环境

环境变量示例（.env.development）：

# 公共配置
VITE_DELETE_CONSOLE=false
VITE_SHOW_SOURCEMAP=true
VITE_APP_PROXY_ENABLE=true
VITE_CLIENT_TYPE_BUYER=buyer
VITE_CLIENT_TYPE_SELLER=seller

# 客户端配置
VITE_BASE_URL=https://ctp-two.10000mao.com

# 应用配置
VITE_APP_TITLE=万贸达
VITE_UNI_APPID=你的应用ID
VITE_APP_PUBLIC_BASE=/
VITE_FALLBACK_LOCALE=zh-Hans

2. Manifest 配置

HarmonyOS 相关配置在 manifest.config.ts 文件的 app-harmony 节点中：

'app-harmony': {
  darkmode: true,
  safearea: {
    background: '#f5f5f5',
    backgroundDark: '#000000',
  },
  useragent: {
    value: 'app-wmall-harmony',
    concatenate: true,
  },
  distribute: {
    bundleName: 'com.wmall.harmo',  // 应用包名
    icons: {
      foreground: 'src/pages-app/static/images/icons/1024x1024.png',
      background: 'src/pages-app/static/images/icons/1024x1024.png',
    },
    // 启动页配置
    splashScreens: {
      startWindowIcon: 'src/pages-app/static/images/splash/splash-harmony.png',
      startWindowBackground: '#FFFFFF',
    },
    modules: {
      'uni-push': {},  // 推送模块
    },
    reqPermissions: [
      // 权限配置...
    ],
    signingConfigs: {
      // 签名配置...
    },
  },
}

关键配置说明

• bundleName: 应用包名，格式为 com.公司名.应用名，需在鸿蒙开发者后台注册
• icons: 应用图标配置，需要提供前景图和背景图
• splashScreens: 启动页配置
• reqPermissions: 应用权限声明
• signingConfigs: 应用签名配置

---

开发工具安装

1. DevEco Studio 安装

下载地址

访问 HarmonyOS 开发者官网 下载 DevEco Studio 。

安装步骤

1. 下载安装包

   • 访问官网下载对应操作系统的安装包
   • macOS: .dmg 文件
   • Windows: .exe 文件

2. 安装 DevEco Studio

   • macOS: 双击 .dmg 文件，拖拽到 Applications 文件夹
   • Windows: 双击 .exe 文件，按照向导安装

3. 首次启动配置

   • 启动 DevEco Studio
   • 选择安装路径和 SDK 路径
   • 等待 SDK 下载完成（包括 HarmonyOS SDK、工具链等）
   • 傻瓜式安装成功即可

2. HBuilderX 安装

项目需要使用 HBuilderX运行到鸿蒙手机：

1. 访问 DCloud 官网 下载 HBuilderX
2. 安装并启动 HBuilderX
3. 安装 uni-app 核心插件和 HarmonyOS 相关插件

---

证书创建流程

1. 注册鸿蒙开发者账号

1. 访问 HarmonyOS 应用开发者门户
2. 注册并登录开发者账号
3. 完成实名认证（个人或企业）

2. 创建应用

1. 登录开发者后台
2. 进入 我的应用 > 创建应用
3. 填写应用信息：
   • 应用名称
   • 应用包名（需与 manifest.config.ts 中的 bundleName 一致）
   • 应用类型
   • 应用分类
4. 提交审核（首次创建需要审核）

3. 创建调试证书

方式一：通过 HbuilderX 创建（测试运行时推荐， 发布正式包需要手动创建）

核心配置文件 manifest.json，如果显示没配置，则运行或发行失败 点击配置，即可显示对应的配置页面

配置调试证书， 点击自动申请调试工具，会自动打开华为开发者网站，需要使用开发者账号登录

方式二：通过 DevEco Studio 创建（推荐）

1. 打开 DevEco Studio
2. 新创建任意一个 HarmonyOS 应用
3. 进入 构建 > 生成私钥和证书请求文件

显示如下

4. 点击 New 按钮，先创建.p12 私钥库文件。证书密码请妥善保管

5. 点击 ok， 自动会先创建的信息
6. 设置 alias 私钥别名，调试别名一般可设置为 debugKey

7. 点击下一步，选择 csr 文件存储路径，并设置名称

8. 点击 finish 完成 证书请求文件 csr 创建, 文件夹内容如下。然后就可以去华为开发者后台创建证书了

方式三：通过命令行创建（看看就行）

# 生成私钥
keytool -genkeypair -alias wmall_debug -keyalg EC -keysize 256 -sigalg SHA256withECDSA -validity 36500 -keystore wmall_debug.p12 -storepass 你的密码

# 导出证书
keytool -exportcert -alias wmall_debug -file wmall_debug.cer -keystore wmall_debug.p12 -storepass 你的密码

4. 添加调试设备

设备 UDID获取方式：HBuildX 运行链接好的鸿蒙手机，点击运行就可以看到

5. 创建应用签名 Profile

1. 登录鸿蒙开发者后台
2. 进入 AppGallery Connect > 选择 证书、APP ID和Profile

4. 选择 新增证书，设置 证书名称， 按需选择 证书类型，选择上面生成好的csr文件，提交即可

6. 选择菜单Profile，点击添加

7. 选择应用

   a. 填写 Profile 文件名称

   b. 选择Profile类型

   c. 选择证书（.csr文件）

   d. 选择测试设备

8. 创建签名 Profile（.p7b 文件）

9. 下载 Profile 文件

5. 配置项目签名

将证书文件放置到项目根目录或指定目录，并在 manifest.config.ts 中配置：

signingConfigs: {
  default: {
    certpath: 'wmall_debug.cer',  // 证书文件路径
    keyAlias: 'wmall_debug',      // 证书别名
    keyPassword: '你的密钥密码',   // 密钥密码（加密后的）
    profile: 'wmall_profileDebug.p7b',  // Profile 文件路径
    signAlg: 'SHA256withECDSA',   // 签名算法
    storeFile: 'wmall_debug.p12', // 密钥库文件路径
    storePassword: '你的密钥库密码', // 密钥库密码（加密后的）
  },
}

安全提示：

• 生产环境证书和密码请妥善保管，不要提交到代码仓库
• 建议使用环境变量或配置文件管理证书信息
• 调试证书仅用于开发测试，不能用于正式发布

6. 发布证书创建

发布证书的创建流程与调试证书类似，但需要注意：

1. 证书类型：选择 Release 类型
2. 证书有效期：建议设置较长的有效期（如 25 年）
3. 证书管理：发布证书需要更严格的管理流程
4. 证书备份：务必备份证书文件和密码

---

项目运行

1. 开发环境运行

前置准备

# 1. 生成环境变量文件
pnpm generate-env

# 2. 生成 Profile 配置（开发环境）
pnpm profile:app:dev

运行

注意：HarmonyOS 平台需要选择运行到鸿蒙。

构建输出

构建完成后，输出目录为：dist/dev/app-harmony

2. 使用 HBuilderX 运行

1. 打开 HBuilderX
2. 选择 文件 > 导入 > 从本地目录导入
3. 选择项目根目录
4. 等待项目加载完成
5. 选择运行到 HarmonyOS 模拟器 或 HarmonyOS 设备

3. 使用 DevEco Studio 运行

1. 打开 DevEco Studio
2. 选择 File > Open
3. 选择构建输出目录：dist/dev/app-harmony
4. 等待项目同步完成
5. 选择运行设备（模拟器或真机）
6. 点击运行按钮

---

模拟器运行

1. 创建 HarmonyOS 模拟器

通过 DevEco Studio 创建

1. 打开 DevEco Studio
2. 进入 Tools

3. 点击 设备管理器 选择需要下载的镜像版本

4.等待 SDK 安装

5. 选择设备类型（Phone、Tablet、TV 等）
6. 选择系统镜像（API 版本）

7. 配置模拟器参数：
   • Name: 模拟器名称
   • Resolution: 分辨率
   • RAM: 内存大小
   • Storage: 存储空间

8. 点击 Finish 创建模拟器

模拟器配置建议

• API Level: 建议使用 API 9+（对应 HarmonyOS 4.0+）
• RAM: 至少 4GB，推荐 8GB
• Storage: 至少 32GB
• Resolution: 根据测试需求选择（如：1080x1920）

2. 启动模拟器

1. 在 Device Manager 中选择已创建的模拟器
2. 点击 启动 按钮
3. 等待模拟器启动完成（首次启动可能需要较长时间）

3. 在模拟器上运行应用

方式一：通过 HBuilderX（推荐）

1. 确保模拟器已启动
2. 在 HBuilderX 中选择运行到 HarmonyOS 模拟器
3. 选择对应的模拟器设备
4. 等待应用安装和启动，如果运行安装项目有问题，重新运行即可
5. 运行成功即可在桌面上看到当前项目的 APP 图标

方式二：通过 DevEco Studio（uniapp 项目不推荐）

1. 确保模拟器已启动
2. 在 DevEco Studio 中选择运行设备为模拟器
3. 点击运行按钮
4. 等待应用安装和启动

4. 模拟器调试

• 日志查看：使用 hdc hilog 命令查看应用日志
• 性能分析：使用 DevEco Studio 的性能分析工具
• 网络调试：配置代理进行网络请求调试

---

项目构建

1. 开发环境构建

# 1. 生成环境变量文件
pnpm generate-env

# 2. 生成 Profile 配置
pnpm profile:app:dev

构建输出目录：dist/dev/app-harmony

注意：HarmonyOS 平台必须使用HBuilderX运行

2. UAT 环境构建

# 1. 生成环境变量文件（如果未生成）
pnpm generate-env

# 2. 生成 Profile 配置
pnpm profile:app:uat

构建输出目录：dist/build/app-harmony

3. 生产环境构建

# 1. 生成环境变量文件（如果未生成）
pnpm generate-env

# 2. 生成 Profile 配置
pnpm profile:app:prod

构建输出目录：dist/build/app-harmony

4. 构建产物说明

构建完成后，在输出目录中会生成以下文件：

dist/build/app-harmony/
├── app.hap              # HarmonyOS 应用包（用于安装）
├── app.debug.hap        # 调试版本应用包
├── app.release.hap      # 发布版本应用包
├── app.app              # 应用配置文件
└── ...                  # 其他资源文件

5. 构建配置说明

构建配置主要在以下文件中：

• vite.config.ts: Vite 构建配置
• manifest.config.ts: 应用清单配置
• pages.config.ts: 页面路由配置
• uno.config.ts: UnoCSS 样式配置

6. 构建优化

代码压缩

生产环境构建会自动启用代码压缩，可在 vite.config.ts 中配置：

build: {
  minify: mode === 'development' ? false : 'esbuild',
  sourcemap: false,  // 生产环境关闭 sourcemap
}

资源优化

• 图片资源：建议使用 WebP 格式
• 代码分割：使用动态 import 实现按需加载
• Tree Shaking：自动移除未使用的代码

---

项目发行

1. 准备发布版本

1.1 更新版本号

在 manifest.config.ts 中更新版本信息：

versionName: '1.0.1',  // 版本名称（用户可见）
versionCode: '114',    // 版本号（内部版本号，递增）

1.2 生成生产环境配置

# 生成生产环境 Profile 配置
pnpm profile:app:prod

1.3 构建生产版本

# 构建生产版本
HBuilderX 发行，选择 App-Harmony-本地打包

2. 应用签名

2.1 使用发布证书签名

确保 manifest.config.ts 中配置了发布证书：

signingConfigs: {
  release: {  // 发布证书配置
    certpath: 'release.cer',
    keyAlias: 'release',
    keyPassword: '发布证书密钥密码',
    profile: 'profileRelease.p7b',
    signAlg: 'SHA256withECDSA',
    storeFile: 'release.p12',
    storePassword: '发布证书密钥库密码',
  },
}

2.2 签名应用包

构建时会自动使用配置的证书进行签名，生成 .hap 文件。

3. 应用上架

3.1 登录开发者后台

1. 访问 HarmonyOS 应用开发者门户
2. 登录开发者账号

3.2 创建应用版本

1. 进入 我的应用 > 选择你的应用
2. 进入 版本管理
3. 点击 创建版本
4. 填写版本信息：
   • 版本号: 与 manifest.config.ts 中的 versionName 一致
   • 版本描述: 本次更新的内容说明
   • 更新类型: 首次发布/版本更新/热更新

3.3 上传应用包

1. 在版本管理页面点击 上传应用包
2. 选择构建生成的 .hap 文件（通常是 app.release.hap）
3. 等待上传完成

3.4 填写应用信息

1. 应用图标: 上传应用图标（1024x1024 PNG）
2. 应用截图: 上传应用截图（至少 3 张）
3. 应用描述: 填写应用功能描述
4. 隐私政策: 提供隐私政策链接
5. 用户协议: 提供用户协议链接

3.5 提交审核

1. 检查所有信息是否完整
2. 点击 提交审核
3. 等待审核结果（通常 1-3 个工作日）

3.6 发布应用

1. 审核通过后，在版本管理页面点击 发布
2. 选择发布渠道（应用市场、自有渠道等）
3. 确认发布信息
4. 点击 确认发布

4. 应用更新

4.1 版本更新

1. 更新 manifest.config.ts 中的版本号
2. 重新构建应用包
3. 在开发者后台创建新版本
4. 上传新的应用包
5. 提交审核并发布

4.2 热更新（暂不支持，后续 uniapp 支持再补充）

HarmonyOS 支持应用热更新（WGT 包）：

1. 构建热更新包（WGT 格式）
2. 在开发者后台上传热更新包
3. 配置更新策略（强制更新/可选更新）
4. 发布热更新

---

常见问题

1. 构建相关

Q: 构建失败，提示证书相关错误

A: 检查以下几点：

1. 证书文件路径是否正确
2. 证书密码是否正确（注意加密后的密码格式）
3. Profile 文件是否与证书匹配
4. 证书是否已过期

Q: 构建输出目录找不到

A: 构建输出目录为：

• 开发环境：dist/dev/app-harmony
• 生产环境：dist/build/app-harmony

2. 运行相关

Q: 模拟器无法启动应用

A: 检查以下几点：

1. 模拟器是否已正常启动
2. 应用包是否已正确签名
3. 应用包名是否与证书配置一致
4. 查看模拟器日志：hdc hilog

Q: 真机调试无法连接

A: 检查以下几点：

1. 设备是否已开启开发者模式
2. USB 调试是否已开启
3. 真机调试插件是否已安装
4. 买个最新的数据线进行设备连接， 数据线协议可能不支持

3. 证书相关

Q: 如何生成证书密码的加密字符串

A: 证书密码需要加密存储，可以使用以下方式：

1. 使用 HBuilderX 的证书管理工具
2. 使用 uni-app 提供的加密工具
3. 手动加密（不推荐，安全性较低）

Q: 证书过期怎么办

A:

1. 创建新的证书
2. 在开发者后台更新证书
3. 更新 manifest.config.ts 中的证书配置
4. 重新构建和签名应用

Q: 如何备份证书

A: 务必备份以下文件：

• .p12 文件（密钥库）
• .cer 文件（证书）
• .p7b 文件（Profile）
• 证书密码和密钥库密码

4. 权限相关

Q: 应用无法获取权限

A: 检查以下几点：

1. 在 manifest.config.ts 中是否已声明权限
2. 权限声明格式是否正确
3. 应用是否已请求权限（HarmonyOS 会在调用相关 API 时自动请求）

5. 发布相关

Q: 应用审核被拒，原因是什么

A: 常见审核被拒原因：

1. 应用信息不完整（缺少图标、截图等）
2. 隐私政策链接无效或内容不符合要求
3. 应用功能异常或崩溃
4. 应用内容不符合平台规范
5. 权限使用说明不清晰

Q: 如何查看审核进度

A:

1. 登录开发者后台
2. 进入 我的应用 > 选择应用 > 版本管理
3. 查看版本状态和审核进度
4. 审核结果会通过邮件或站内信通知

Q: 应用上架后如何更新

A:

1. 更新版本号（versionName 和 versionCode）
2. 重新构建应用包
3. 在开发者后台创建新版本
4. 上传新的应用包
5. 提交审核并发布

6. 开发相关

Q: 如何调试 HarmonyOS 应用

A:

1. 日志调试: 使用 console.log 查看日志
2. 性能分析: 使用 DevEco Studio 的性能分析工具
3. 网络调试: 配置代理进行网络请求调试

---

附录

A. 相关链接

• HarmonyOS 开发者官网
• uni-app 官方文档
• DevEco Studio 下载
• HarmonyOS API 参考

B. 项目文件结构

uniapp-wmall/
├── dist/                    # 构建输出目录
│   ├── dev/                 # 开发环境构建
│   │   └── app-harmony/     # HarmonyOS 开发版本
│   └── build/               # 生产环境构建
│       └── app-harmony/     # HarmonyOS 生产版本
├── src/                     # 源代码目录
│   ├── pages-app/           # APP 专用分包
│   │   ├── static/          # 静态资源
│   │   │   └── images/
│   │   │       ├── icons/   # 应用图标
│   │   │       └── splash/  # 启动页图片
│   └── profile.json         # Profile 配置（自动生成）
├── manifest.config.ts       # 应用清单配置
├── vite.config.ts           # Vite 构建配置
├── pages.config.ts          # 页面路由配置
├── env-conf.ts              # 环境配置源文件
└── package.json             # 项目依赖配置

D. 版本号规范

• versionName: 用户可见的版本号，格式：主版本.次版本.修订版本（如：1.0.1）
• versionCode: 内部版本号，每次发布必须递增（如：114）

E. 证书文件说明

• .p12: 密钥库文件，包含私钥和证书
• .cer: 证书文件，包含公钥
• .p7b: Profile 文件，包含应用签名配置信息

---

Happy Coding! 🎉