系列:《Web 到 HarmonyOS》· 第 10 篇
适合人群:会 Vue3 + Vite,知道
dist、路由懒加载和manualChunks,准备看懂鸿蒙应用最后打成什么
写在前面
Vue 工程里,npm run build 之后你拿到的是 dist:一个入口页,若干按路由拆开的 js,公共依赖有时再抽成一个 chunk。鸿蒙上架前做的是同一件事,产物名字换成 HAP、HAR、HSP,最后收成一个 .app。
能装到手机上、点图标能进的是 HAP 。编译时打进使用方、每个使用方各留一份的是 HAR 。自己编成独立文件、运行时全应用只留一份的是 HSP。
| 你在 Vue / Vite 里见过的 | 鸿蒙产物 | 它实际干什么 |
|---|---|---|
站点入口 index.html + 主包 |
entry 型 HAP(.hap) |
应用入口。同一设备类型只能有一个 entry |
| 可后装的一整块业务,不只是一个懒加载路由 | feature 型 HAP | 动态特性模块,能单独安装,仍属于这一个应用 |
| 被打进每个应用的内部组件库 | HAR(.har) |
编译期复用。用一次,拷一份 |
manualChunks / splitVendorChunk 抽出的共享 chunk |
HSP(.hsp) |
运行期复用。磁盘和进程里都只有一份 |
| 私有包集成进多个应用,运行时身份必须跟宿主一致 | 集成态 HSP | 发布时不绑包名,集成时改成宿主的 bundleName 再重签 |
| 整个站点 | Bundle | 一个应用里全部 HAP 和 HSP。bundleName 是唯一标识 |
| 你交给发布系统的那一包 | App Pack(.app) |
上架的基本单元 |
manifest.json / 构建清单 |
pack.info |
记下每个 HAP、HSP 的名字、类型、Ability |
package.json |
oh-package.json5 |
声明依赖 |
package.json 的 exports、桶文件 index.ts |
模块根上的 index.ets |
只有从这里再导出的,外面才用得到 |
| npm | OHPM | HAR 可以发到这里,给别的应用用 |
签名按 HAP、HSP、APP 各自签。云端分发和手机上的安装,按 HAP 和 HSP 这两个文件走。上架时交的是一个 .app,装到设备上时,系统拿出来装的是里面的一个个 .hap 和 .hsp。
本仓库还是单 entry,下面先对上现有工程,再写「要拆共享模块时」怎么接。模块和路由的总图见 02-ability-stage-module-router.md。
一、本仓库现在就是一个入口包
AppScope/app.json5 是应用身份,相当于站点的 origin:包名、版本、图标、名称。
1:9:AppScope/app.json5
{
"app": {
"bundleName": "com.example.myapplication",
"vendor": "example",
"versionCode": 1000000,
"versionName": "1.0.0",
"icon": "$media:layered_image",
"label": "$string:app_name"
}
}
entry 的 type 是 entry,桌面点进来的 Ability 记在 mainElement。这就是 Vue 工程里那个唯一的 index.html。
1:11:entry/src/main/module.json5
{
"module": {
"name": "entry",
"type": "entry",
"description": "$string:module_desc",
"mainElement": "EntryAbility",
"deviceTypes": [
"phone"
],
"deliveryWithInstall": true,
"installationFree": false,
工程级 build-profile.json5 的 modules 里目前只有 entry。根上和 entry 的 oh-package.json5 都还没有业务依赖。也就是说:现在没有 HAR,也没有 HSP,打出来就是一个 HAP,再包进 .app。
依赖以后写在模块的 oh-package.json5,和 Vue 子包自己的 package.json 一样,不要写到错的那一层。官方还要求:用 overrides 锁版本时,必须写在工程根 的 oh-package.json5,写在模块级不会生效。
二、HAP:能跑起来的那一层
HAP 全称 Harmony Ability Package。一个 .hap 里是代码、资源、三方库和配置,是安装和运行的基本单元。一个应用至少有一个 HAP。
两种类型:
| 类型 | module.json5 的 type |
Vue 对照 | 约束 |
|---|---|---|---|
| entry | entry |
主应用。用户点图标进来 | 同一设备类型只能有一个 entry。入口 Ability 的 skills 带 entity.system.home 和 ohos.want.action.home |
| feature | feature |
可以后装的一整块业务 | 可以有多个,也可以没有。能单独安装,仍然属于这一个 bundleName |
这里和 Vue 路由懒加载要分开。
() => import('./views/Vip.vue') 仍然在同一个 dist 里,只是另一个 js 文件。它更接近同一个 HAP 内部的动态 import,不是 feature。
feature 是应用市场可以晚一点才装上的功能模块。用户第一次下载可以不带它,用到再装。官方把这类做法叫按需分发。那是「这个功能要不要下载」,和下一节「这段代码会不会在多个包里各拷一份」是两件事。
三、HAR:编译期被吃掉的组件库
HAR 全称 Harmony Archive,静态共享包,后缀 .har。可以放 ArkTS、C++ so、资源和配置。它能在本工程里共享,也能发到 OHPM。它不能单独装到手机上。
对照 Vue:monorepo 里一个 packages/ui,被 apps/main 和 apps/admin 同时依赖。Vite 默认会把这个包打进每一个应用的产物 。线上看不到 packages/ui 这个目录,只能在每个 bundle 里看到它的代码。HAR 一样。
编译 HAP 或 HSP 时,它们依赖的 HAR 会被直接编进去。所以拆开最终的 .app,只能看到 .hap 和 .hsp,看不到 .har。使用方编出来的 module.json 里,dependencies 能看到 HSP 的模块名,看不到 HAR------HAR 当时已经变成使用方字节码的一部分。ets 源码在这一步编成 .abc。
多个使用方各打一份,就是包变大的原因。两个入口都 import 了同一份大组件库,又没有抽共享 chunk,dist 里就有两份。HAR 的多包引用就是这个结果。
单 HAP 工程里这通常不是问题:只有一个使用方,拷贝只发生一次。本仓库现在就是这种。公共组件、工具函数、model,先放 HAR 就够。
四、HSP:运行时只留一份
HSP 全称 Harmony Shared Package,动态共享包,后缀 .hsp。内容和 HAR 一样可以有代码、so、资源、配置,但它独立编译 。多个 HAP 引用它,.app 里只留这一份;进程里也只有一份。
对照 Vite:两个入口都依赖同一块很大的业务代码时,用 build.rollupOptions.output.manualChunks 把它抽成单独的 chunk,两个入口改成去引用这个 chunk。HSP 就是这个共享 chunk,而且系统保证运行时只加载一份。官方还说明:HSP 在运行时按需加载。
它跟着宿主应用走,有三条 Vue 经验对不上的边界。
和宿主绑在一起。 应用内 HSP 不能单独上架。它跟宿主的 .app 一起发布,和宿主同进程、同 bundleName、同生命周期。编译时就和这个包名耦合,只能给这一个应用用。
多个应用要共用,用集成态 HSP。 它是应用内 HSP 的中间产物。构建、发布时不跟某一个包名焊死;用的时候,工具链把包名换成宿主的 bundleName,重新签名,生成的新 HSP 才是宿主自己的安装包。适合同一个组织里多个应用共享代码和资源。
依赖不传递,也不能转圈。 HSP 可以依赖别的 HAR 或 HSP,也可以被 HAP、HSP 依赖。A 依赖 B、B 依赖 C 时,A 不能直接使用 C 的方法和组件。npm 里靠提升有时还能「碰巧引到」,这里不行。A → B → C → A 这种环也不允许。
从 API 14 起,HSP 可以在配置里声明 UIAbility,但不能做成桌面入口(不能配 entity.system.home + ohos.want.action.home)。从 API 18 起可以声明 ExtensionAbility,同样不能当入口。
五、从源码到上架
开发、编译、发布是三种形态。
开发态就是工程目录,和 Vue 仓库对应:
| 鸿蒙 | Vue 工程 |
|---|---|
AppScope/app.json5 |
应用名、版本、图标。没有浏览器那一层,包名写在这里 |
模块/src/main/module.json5 |
这个包是 entry、feature 还是 shared,以及 Ability、权限、页面 |
模块/src/main/ets |
src/**/*.vue 里的脚本。ArkUI 没有单独的 .vue 模板文件 |
AppScope/resources、模块/src/main/resources |
public/ 和各包自己的静态资源 |
oh-package.json5 |
package.json 的 dependencies |
build-profile.json5、hvigorfile.ts |
vite.config.ts。签名、产品、构建模式写在这里 |
编译时还有两件合并:AppScope/resources 会合进模块资源,两边同名时留下应用级那份;app.json5 会合进模块配置,生成最终的 module.json。
发布态把所有 .hap 和 .hsp 收成一个 Bundle,再打成 .app。DevEco Studio 同时生成 pack.info,记下 bundleName、versionCode,以及每个模块的 name、type、abilities。.hsp 可以没有。本仓库现在就是「一个 entry HAP + 一个 .app」。
六、多包以后,拷贝发生在哪
多个 HAP 直接依赖同一组 HAR 时,每个 HAP 都会把这些 HAR 再编译进去。官方的例子是:HAP1,以及 HAP2(或另一个 HSP1),都引用了 HAR2 和 HAR3。打完包,HAR2、HAR3 各有多份。
把 HAR2 和 HAR3 收进一个 HSP2,让 HAP1、HAP2 只依赖 HSP2。HAR 仍然会被编译进它的使用方,但使用方现在只有 HSP2,所以这两份 HAR 在整个 .app 里只出现一次。HAR2 加 HAR3 的体积超过 HSP 自身开销时,包会变小。
这和两个 Vite 入口各打一份大依赖、改成抽一个共享 chunk,是同一笔账。
官方同时写了反面:大量用 HSP 替换 HAR,会拉高编译时间和内存。引用这些 HSP 的模块在编译时会触发更多语言编译任务。小组件、工具函数继续用 HAR。
七、接一个 HSP,和接 workspace 包一样
本仓库还没有 library 模块。下面是按官方接法,把一块共享能力拆出去时要写的文件。依赖源码用 file:,和 pnpm workspace 的 workspace:* 同一角色。
HSP 的 module.json5 里 type 为 shared。对外只认根上的 index.ets,没从这里导出的,使用方引不到。这就是 exports。
typescript
// library/src/main/ets/utils/Calc.ets
export class Calc {
static add(a: number, b: number): number {
return a + b;
}
}
typescript
// library/index.ets
export { Calc } from './src/main/ets/utils/Calc';
json5
// entry/oh-package.json5
{
"name": "entry",
"dependencies": {
"library": "file:../library"
}
}
typescript
// entry/src/main/ets/pages/Index.ets
import { Calc } from 'library';
@Entry
@Component
struct Index {
@State result: number = 0;
build() {
Column() {
Text(`计算结果:${this.result}`)
Button('调用 HSP')
.onClick(() => {
this.result = Calc.add(1, 2);
})
}
}
}
依赖已经打好的产物时:HAR 用 .har,HSP 用 release 构建出来的 .tgz,写成 "library": "file:../library.tgz",然后执行 ohpm install。配置好之后,调用方式和 HAR 相同。
资源不要用相对路径字符串。在 HSP 里写 Image("../../resources/base/media/example.png"),实际会去使用方 (比如 entry)的资源目录找。Vite 里相对路径相对于写这行代码的文件;这里这串路径会落到调用方。HSP 自己的资源用 $r('app.media.example')。要给外面用的图和文案,包一层管理类再从 index.ets 导出,内部改名时使用方不用跟着改。
页面若要从 entry 进到 HSP 里的某个页,用 Navigation 的路由表,在 HSP 的 module.json5 里加 routerMap。整页入口和 Tab 内下钻的区别,仍按第 02 篇:换整页用 router,在当前业务流里往下钻用 Navigation。
八、怎么选
| 场景 | 用什么 | Vue 里你大概已经这么做 |
|---|---|---|
| 一个 HAP,复用的是组件和工具函数 | HAR | 单页应用里抽 components/、utils/,打进唯一的 bundle |
| 多个 HAP,共享一大块业务、资源和 so | HSP | 多入口工程把大依赖抽成共享 chunk |
| 公开给别的应用用的库 | HAR,发到 OHPM | npm publish 一个组件库 |
| 同一组织里多个应用共用 | 集成态 HSP | 私有包,集成时改成宿主包名并重新签名 |
| 不常用的整块功能,希望用户用到再下 | feature 型 HAP | 独立子应用,晚于主包安装。不是路由懒加载 |
本仓库下一步如果只是把公共 UI 从 entry 里抽出,用 HAR。等到真的出现第二个 HAP,而且两边都要带同一块很大的业务,再把这块收进 HSP。
口诀:一个入口里的复用用 HAR;多个安装包里的大块共享用 HSP;要单独下载的功能用 feature HAP。