《Web 到 HarmonyOS》-- 打包:Vite 产物 → HAP / HAR / HSP

系列:《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,同样不能当入口。


五、从源码到上架

开发、编译、发布是三种形态。

flowchart LR subgraph dev [开发态] src[entry 的 ets] harSrc[HAR 模块] hspSrc[HSP 模块] end subgraph build [编译态] hap[entry.hap / feature.hap] hspFile[library.hsp] end subgraph ship [发布态] app["App Pack .app"] info[pack.info] end src --> hap harSrc --> hap harSrc --> hspFile hspSrc --> hspFile hap --> app hspFile --> app app --> info

开发态就是工程目录,和 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 自身开销时,包会变小。

flowchart TB subgraph copies [多个 HAP 直接依赖 HAR] HAP1 --> HAR2 HAP1 --> HAR3 HAP2 --> HAR2b[HAR2 的另一份] HAP2 --> HAR3b[HAR3 的另一份] end subgraph once [改由一个 HSP 承载] HAP1b[HAP1] --> HSP2 HAP2b[HAP2] --> HSP2 HSP2 --> onceHar[HAR2 与 HAR3 只编译进 HSP2 一次] end

这和两个 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。

相关推荐
inksci16 分钟前
用飞帆做了个小网页
前端·javascript·css·html
去伪存真19 分钟前
被 pnpm 打包坑惨后,我彻底盘明白了硬链接与软链接
前端·electron
zhensherlock1 小时前
Protocol Launcher 系列:CodeHub 移动端 GitHub 协作利器
前端·javascript·typescript·node.js·自动化·github·js
tryCbest6 小时前
Vue3——第 22 篇:Pinia——新一代状态管理(上)
前端·javascript·vue.js
bai2736 小时前
"👨‍👩‍👧‍👦" 的 length 是 11:我把自己写的字数统计脚本拖出来审了一遍
前端·javascript
zhanlang02178 小时前
HTML 零基础入门到企业实战【第八章 8.5】画布 canvas、SVG 矢量图形基础入门
前端·html
星云_byto9 小时前
CSS面试题
前端·css
zhanlang02179 小时前
HTML 零基础入门到企业实战全套教程【连载 8.4】HTML5 新增表单属性与表单控件
前端·html·html5
科研邪修法17 小时前
PDF新增页面文字与文本批注怎么区分?以双版本培训讲义为例
前端·css·pdf