ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

首页/资讯中心/资讯详情

HarmonyOS HAR开发全攻略：从模块打包到工程化实践

发布时间：2026/8/16 23:17:15 拓冰企业网站定制
HarmonyOS HAR开发全攻略：从模块打包到工程化实践

1. 从“模块”到“积木”：理解HarmonyOS HAR的价值

在HarmonyOS应用开发中，尤其是当项目规模逐渐增大、团队协作成为常态时，一个绕不开的话题就是代码和资源的复用与共享。想象一下，你开发了一个非常精美的自定义弹窗组件，或者封装了一套通用的网络请求工具，你肯定不希望在每个新项目中都把这些代码复制粘贴一遍。这时候，HAR（HarmonyOS Ability Resources）就登场了。你可以把它理解为一个“功能积木包”，它允许你将可复用的代码、资源、C++库等打包成一个独立的模块，然后在其他应用中像搭积木一样引用它。这不仅仅是代码管理上的优雅，更是工程化、组件化开发的基石。对于任何希望提升开发效率、保证代码一致性、实现团队内能力沉淀的HarmonyOS开发者来说，掌握HAR的打包与引用是必备技能。今天，我们就来彻底搞懂这块“积木”的制作与使用全流程。

2. HAR的构成与打包前的关键决策

在动手打包之前，我们必须先弄清楚HAR里面到底能装什么，以及如何规划我们的“积木”。一个标准的HAR包，其内部结构遵循HarmonyOS模块的约定，主要包含以下几个部分：

  • ArkUI组件/页面：这是HAR最常见的用途，将自定义的@Component组件或整个页面（Page）打包，供其他模块使用。
  • TS/JS工具类与工具函数：例如日期处理、字符串格式化、加解密、业务逻辑的通用工具等。
  • 资源文件：包括图片、字体、音频、视频、string.json、color.json等。需要注意的是，HAR中的资源在引用时，其路径和访问方式与本地资源略有不同。
  • C++库（可选）：如果你的功能涉及高性能计算或底层能力，可以将C++源码或预编译的.so库打包进HAR。
  • 配置文件：主要是oh-package.json5，它定义了HAR的元数据，如名称、版本、描述、依赖、导出声明等，其角色类似于Node.js的package.json。

2.1 规划你的HAR：原子化与聚合度的权衡

在创建HAR模块时，第一个要思考的问题是：我这个HAR应该包含多少功能？是做一个“大而全”的通用工具库HAR，还是做多个“小而美”的专项功能HAR？

我的经验是，优先考虑“单一职责”和“高内聚”。举个例子，如果你有一个网络请求库和一个UI组件库，我更建议将它们拆分成两个独立的HAR：@myorg/http和@myorg/ui-components。这样做的好处非常明显：

  1. 依赖清晰：一个只需要网络请求的项目，就不必引入庞大的UI组件库，减少了最终应用包的体积。
  2. 迭代独立：网络请求库的升级和UI组件库的升级可以互不干扰，版本管理更清晰。
  3. 复用性更高：小而专的模块更容易被不同的项目组合使用。

当然，如果一组功能关联性极强，总是被同时使用，打包在一起也是合理的。例如，一个“用户认证”HAR，里面可能包含了登录/注销的UI页面、Token管理工具类和相关的API接口封装，它们共同完成一个完整的业务闭环，打包在一起就更合适。

2.2 环境准备与模块创建

确保你的DevEco Studio是最新版本，并且已经配置好HarmonyOS SDK。创建一个HAR模块非常简单：

  1. 在现有工程中，点击File->New->Module。
  2. 在弹出的窗口中，选择Static Library模板下的HarmonyOS Library。这里有一个关键点：HarmonyOS Library 默认生成的就是HAR模块。而Shared Library则是用于共享C++代码的HAR。
  3. 为你的HAR模块命名，例如mylibrary。点击Finish。

DevEco Studio会自动为你生成一个标准的HAR模块结构，其中最关键的文件就是oh-package.json5。让我们立即打开它，看看里面有什么。

3. 核心配置文件oh-package.json5的深度解析

这个文件是HAR的“身份证”和“说明书”，任何HAR的打包与引用都绕不开它。一个典型的配置如下：

{ "name": "@myorg/mylibrary", "version": "1.0.0", "description": "My custom HarmonyOS library", "main": "./Index.ets", "types": "./Index.ets", "author": "yourname", "license": "Apache-2.0", "dependencies": {}, "devDependencies": {}, "peerDependencies": {}, "har": { "dependencies": [ { "name": "@ohos/http", "version": "1.0.0" } ], "profile": { "compileMode": "esmodule", "runtimeMode": "classic", "target": "default" }, "buildOption": { "apiType": "public", "allowNative": false } } }

我们来逐一拆解其中最关键的几个字段：

  • name与version：这是HAR的唯一标识。强烈建议使用@scope/name的格式（如@mycompany/ui-kit），这符合现代包管理的惯例，也能有效避免与公共仓库的包名冲突。version必须遵循语义化版本规范（SemVer），这对于后续的依赖管理和升级至关重要。
  • main与types：这指向了HAR的“入口文件”。当其他模块引用你的HAR时，可以通过import { something } from '@myorg/mylibrary'这样的语句来导入。Index.ets文件就是你对外暴露所有API的“总出口”。通常，你会在Index.ets中export所有希望外部能访问的模块。
  • har.dependencies：这里声明的是你的HAR运行时所依赖的其他HAR包。注意，它和顶层的dependencies含义不同。顶层的dependencies更多用于工具链（如TypeScript类型定义），而har.dependencies是HarmonyOS运行时必须的。这是一个非常容易混淆和踩坑的地方！如果你的HAR使用了@ohos/http这个系统能力，就必须在这里声明，否则引用你HAR的应用在运行时可能会找不到这个模块而崩溃。
  • har.buildOption.apiType：这个字段决定了HAR中哪些内容可以被外部访问。
    • "public"：默认值。只有被明确export的内容才对外可见。这是推荐的做法，符合封装原则。
    • "system"：HAR内的所有内容（包括未export的）对同一应用下的其他HAR可见，但对应用本身不可见。用于复杂模块内部拆分。
    • "restricted"：最严格，仅对同一oh-package.json5文件下的其他模块可见。很少使用。

实操心得：在团队协作中，务必在项目初期约定好name的命名规范和version的升级策略。对于har.dependencies，每次添加新的系统能力依赖时，都要记得检查并更新这里，最好在HAR的README中明确列出其运行时依赖，避免给使用者带来惊喜（吓）。

4. 编写与导出：打造一个健壮的HAR模块

有了正确的配置，接下来就是编写HAR内部的代码了。这里的关键在于如何正确地组织文件和导出API。

4.1 创建入口文件Index.ets

在HAR模块的根目录（与oh-package.json5同级）创建Index.ets文件。这个文件应该非常简洁，只做一件事：重新导出所有你需要公开的模块。

// Index.ets export { MyButton } from './src/main/ets/components/MyButton' export { formatDate } from './src/main/ets/utils/DateUtils' export { HttpClient } from './src/main/ets/net/HttpClient' // ... 导出其他所有需要公开的类、函数、常量

这样做的好处是，使用者只需要记住一个入口（@myorg/mylibrary），就能找到所有功能，而不需要去深究HAR内部复杂的目录结构。

4.2 资源文件的处理与引用

资源文件（如图片、i18n字符串）的打包和引用是另一个重点。HAR中的资源在编译时会被打包进去，但在引用时，不能使用相对路径。

错误示范（在引用HAR的应用中）：

Image($r('app.media.icon_from_har')) // 这样是找不到的！

正确做法：在HAR模块内部，资源引用和普通模块一样使用$r('app.media.icon')。但是，当其他应用或模块引用这个HAR时，需要通过HAR的模块名来访问其资源。

假设你的HAR模块名为mylibrary，里面有一张图片资源icon.png，其定义在resources/base/media/下。

  1. 在HAR内部代码中引用该图片（这是正常的）：

    Image($r('app.media.icon'))

  2. 在引用该HAR的另一个应用或模块中，要使用这张图片，你必须使用完整的资源引用语法，并指定模块名：

    // 语法：$r('模块名.type.name') Image($r('mylibrary.media.icon'))

踩坑记录：曾经在一个项目中，UI同学把一套图标资源做成了HAR，但文档里没说明引用方式。开发同学在业务模块里用$r('app.media.xxx')引用，一直报资源找不到，排查了很久才发现问题所在。所以，如果你的HAR包含了资源，一定要在文档中明确指出外部引用时需要加上模块名前缀。

4.3 关于C++代码的打包

如果你的HAR包含C++代码（例如cpp目录），在打包时，这些代码会被编译成对应的库。对于引用方来说，他们不需要关心C++的实现细节，只需要像调用普通的TS/JS API一样使用HAR暴露出来的接口即可，HarmonyOS的方舟运行时和FFI（Foreign Function Interface）机制会处理好底层的交互。在oh-package.json5中，如果包含C++代码，通常需要设置"allowNative": true。

5. 打包、发布与本地引用

5.1 打包HAR

在DevEco Studio中，打包HAR非常简单：

  1. 在工程视图中，右键点击你的HAR模块（例如mylibrary）。
  2. 选择Build->Build HAP(s)/APP(s)->Build HAR。

DevEco Studio会在该HAR模块的build目录下（默认路径是mylibrary/build/default/outputs/default/）生成一个.har文件，例如mylibrary-default-1.0.0.har。这个.har文件本质上就是一个压缩包，你可以用解压软件查看其内部结构，里面包含了编译后的代码、资源和元数据。

5.2 本地引用HAR（适用于项目内模块复用）

这是最常见的场景。假设你的主应用模块叫entry，你想引用刚才打包的mylibraryHAR。

  1. 配置依赖：打开主模块（如entry）下的oh-package.json5文件。
  2. 添加依赖：在dependencies字段中添加你的HAR。由于是本地模块，可以使用file:协议指定相对路径。
    { "dependencies": { "@myorg/mylibrary": "file:../mylibrary" } }
  3. 同步项目：点击DevEco Studio右上角的Sync按钮，或者打开工具窗口的Terminal，在项目根目录执行ohpm install。这会自动将HAR模块链接到当前项目。
  4. 导入使用：在你的业务代码中，就可以像使用npm包一样导入HAR导出的内容了。
    import { MyButton, formatDate, HttpClient } from '@myorg/mylibrary' @Entry @Component struct Index { build() { Column() { // 使用HAR中的组件 MyButton({ label: 'Click Me' }) Text(formatDate(new Date())) } } }

5.3 发布到私有仓库（适用于团队共享）

对于团队协作，将HAR发布到公司内部的私有OHPM（Open Harmony Package Manager）仓库是更专业的做法。这类似于在公司内部搭建一个Nexus或Verdaccio服务来管理npm包。

  1. 配置仓库地址：在项目根目录的oh-pm.json5或全局OHPM配置中，添加你的私有仓库地址。
  2. 登录仓库：在终端执行ohpm login --registry=你的私有仓库地址。
  3. 发布HAR：在HAR模块目录下，执行ohpm publish。这个命令会读取oh-package.json5中的name和version，并将.har文件发布到配置的仓库。
  4. 在其他项目中引用：在其他项目的oh-package.json5中，直接添加依赖即可，OHPM会自动从配置的仓库中拉取。
    { "dependencies": { "@myorg/mylibrary": "^1.0.0" } }

注意事项：发布前，请务必检查oh-package.json5中的信息是否准确，特别是version。一旦发布，同一个版本号的内容通常是不可覆盖的，需要升级版本号重新发布。

6. 高级场景与疑难排查

6.1 依赖冲突与版本管理

当你的应用同时引用了多个HAR，而这些HAR又间接依赖了同一个包的不同版本时，就可能发生依赖冲突。OHPM会尝试解决，但并非总能完美处理。

解决方案：

  1. 使用peerDependencies：如果你的HAR只是“建议”或“要求”宿主环境提供某个库（特别是像React、Vue这样的框架或核心工具库），应该将其声明在peerDependencies中，而不是dependencies或har.dependencies。这能将版本决定权交给最终的应用。
  2. 依赖扁平化与锁定：OHPM安装依赖时会产生oh-lock.json5文件，它锁定了所有直接和间接依赖的确切版本，保证了团队所有成员和环境的一致性。务必将其纳入版本控制系统（如Git）。
  3. 主动升级与测试：定期检查并升级依赖的HAR版本，在测试环境中充分验证，避免累积大量过期依赖导致最终升级困难。

6.2 HAR热更新与动态加载的误区

一个常见的误解是：HAR能否实现热更新？答案是否定的，至少目前的标准机制不支持。HAR的代码和资源在应用编译时就被打包进最终的HAP（HarmonyOS Ability Package）文件中。应用商店分发和用户安装的是HAP。因此，更新HAR中的代码，必须发布新版本的应用，通过应用商店更新机制来完成。

对于需要动态下发的业务模块，HarmonyOS提供了“动态共享包”（.hsp）的方案。HSP在设计上就支持在应用安装后从网络下载并加载，更适合插件化、动态化的场景。在选择HAR还是HSP时，要根据“是否需要动态更新”这个核心需求来决定。

6.3 常见编译与运行时错误排查

  • 错误：Module not found: @myorg/mylibrary

    • 检查1：确认引用方oh-package.json5的dependencies已正确添加，且模块名、路径无误。
    • 检查2：执行ohpm install或点击Sync同步项目。
    • 检查3：检查HAR模块本身的oh-package.json5中name字段是否与引用时写的完全一致（包括@scope）。

  • 错误：The requested module '@ohos/xxx' does not provide an export named 'yyy'

    • 检查：这通常是HAR的har.dependencies声明有问题。确认你使用的系统能力（如@ohos/http）已经正确声明在该字段中，并且版本号兼容。

  • 错误：资源ID找不到（Resource id not found）

    • 检查：百分之九十的情况是资源引用语法错误。牢记在外部引用HAR资源时必须使用$r('har_module_name.type.name')格式。确认模块名、资源类型（media,string等）和资源名都正确。

  • HAR修改后，引用方未生效

    • 操作：HAR模块修改后，需要重新执行Build HAR操作来生成新的.har文件。然后，在引用方项目中，可能需要执行ohpm install或清理构建缓存（Build->Clean Project/Rebuild Project）来确保拉取到最新版本。

7. 工程化实践：将HAR融入开发流水线

在真实的团队开发中，HAR的管理需要融入整个CI/CD（持续集成/持续部署）流水线。

  1. 版本号自动化：可以利用脚本，在每次合并代码到主分支时，根据git commit信息自动提升HAR的版本号（如遵循fix升补丁号、feat升次版本号等Conventional Commits规范），并更新oh-package.json5。
  2. 自动化打包与发布：在CI服务器（如Jenkins, GitLab CI）上，配置流水线任务，在代码通过测试后，自动执行ohpm publish将HAR发布到私有仓库。
  3. 依赖更新检查：可以集成类似ohpm outdated的命令到流水线或日常脚本中，定期检查项目依赖的HAR是否有新版本，并生成报告，辅助决策升级。
  4. 文档与示例代码：一个优秀的HAR必须配有清晰的README.md，说明其功能、安装方式、API文档和至少一个最小化的使用示例。可以考虑在HAR项目中直接维护一个example目录，展示典型用法。

从我过去多个HarmonyOS项目的实践经验来看，早期花时间搭建好HAR的创建、发布、引用和更新规范，能为项目后期带来巨大的可维护性红利。它让核心能力得以沉淀，让团队协作像拼装乐高一样高效，是应对复杂应用开发的利器。开始规划你的第一个HAR模块吧，从封装一个最简单的工具函数或组件开始，你会立刻感受到这种模块化设计带来的清爽。

网站建设 企业官网 运营推广
返回列表