HarmonyOS共享包开发：从Index.ets报错到完整导出ArkUI组件的解决方案

原创

于 2026-02-26 15:03:27 发布 · 2.8k 阅读

HarmonyOS共享包实战：从Index.ets报错到组件导出的深度解析与避坑指南

最近在折腾HarmonyOS的共享包开发，不少刚入门的开发者朋友都踩过同一个坑：兴致勃勃地创建了一个HAR（Harmony Archive）模块，准备把封装好的精美ArkUI组件分享给其他模块使用，结果在引用时，DevEco Studio毫不留情地抛出一个错误——Importing ArkTS files to JS and TS files is not allowed. <ArkTSCheck>。这个报错就像一盆冷水，瞬间浇灭了共享代码的热情。其实，这个问题的根源往往不在于你的组件写得不好，而在于那个看似不起眼的入口文件配置。今天，我们就以这个经典报错为起点，深入聊聊HarmonyOS中HAR和HSP这两种共享包的开发、配置与实战应用，帮你彻底理清从组件封装到跨模块引用的完整链路。

共享包的本质是为了解决代码复用和模块化的问题。无论是将一个通用的按钮样式、一套工具函数库，还是一个复杂的业务组件封装起来，共享包都能让这些资产在应用的不同部分，甚至不同应用间（有一定限制）高效流转。理解HAR与HSP的区别、掌握正确的导出姿势，是构建可维护、高性能HarmonyOS应用的关键一步。本文面向已经熟悉HarmonyOS基础开发，但在模块化实践中遇到障碍的开发者，我们将绕过官方文档的平铺直叙，直接切入实战场景，手把手带你解决问题，并分享一些官方文档里可能没细说的“经验之谈”。

1. 破解“Index.ets”迷思：入口文件的正确打开方式

那个令人头疼的 Importing ArkTS files to JS and TS files is not allowed 错误，十有八九是因为入口文件类型配置不当。很多开发者（包括早期的我）会下意识地认为，既然HarmonyOS主力开发语言是ArkTS，那么共享包的入口文件自然应该是 index.ets。DevEco Studio在创建某些类型的模块时，也可能会默认生成这个文件。然而，在共享包（特别是HAR）的上下文中，这个默认选择可能就是个“陷阱”。

这个报错的深层含义是什么？ 简单来说，工具链在解析模块依赖时，对入口文件的类型有严格的期望。当你在一个使用TypeScript/JavaScript模块解析规则的上下文中（例如其他模块的 import 语句），试图直接引入一个 .ets 文件作为模块入口时，类型检查器（ArkTSCheck）就会抛出这个错误，因为它期望的是一个 .ts 或 .js 类型的声明文件。.ets 文件包含了ArkUI的视图语法，不能直接作为纯类型声明的入口。

注意：这里的关键在于模块系统的认知。共享包的入口文件主要作用是声明导出项，而不是执行UI渲染。因此，一个纯类型的 .ts 文件是更合适的选择。

那么，正确的做法是什么？答案是将入口文件改为 index.ts。这个文件是你的共享包对外的“总目录”，所有希望暴露给其他模块使用的接口、组件、资源，都需要在这里统一登记。

如何创建和配置 index.ts？

定位你的共享包模块：在DevEco Studio的项目视图中，找到你的HAR或HSP模块。
创建或重命名入口文件：在模块的根目录（通常与 oh-package.json5 同级）下，创建一个名为 index.ts 的文件。如果已存在 index.ets，建议将其重命名或删除，避免混淆。
配置 oh-package.json5：这是最关键的一步。打开模块内的 oh-package.json5 文件，找到或添加 main 字段，将其值指向你刚刚创建的 index.ts 文件。
```
// 你的HAR/HSP模块下的 oh-package.json5
{
  "main": "./index.ts",
  // ... 其他依赖项配置
}
```