鸿蒙应用开发：鸿蒙项目中使用私有 npm 插件的完整流程

本文档描述如何在一个 HarmonyOS（鸿蒙）项目中引入并使用一个发布在私有 npm 仓库中的插件（如 @yourcompany/yourplugin），包括 .npmrc 配置、依赖安装、插件导入与注册等步骤。

🔧 一、前置条件

已安装 DevEco Studio
Node.js 环境正常（DevEco 自带）
拥有私有 npm 仓库地址及认证权限
插件已发布到私有仓库（如：@yourcompany/yourplugin）

📁 二、配置 .npmrc 文件（设置私有仓库地址与认证）

✅ 步骤：

在项目的根目录下创建或修改文件：.npmrc
添加如下内容（根据实际信息填写）：

Ini 复制代码

# 设置默认镜像源为国内加速镜像（可选）
registry=https://mirrors.huaweicloud.com/repository/npm/

# 对 @ohos 开头的包使用鸿蒙官方仓库
@ohos:registry=https://repo.harmonyos.com/npm/

# 对 @yourcompany 开头的包使用私有仓库
@yourcompany:registry=https://your-private-registry-url/

# 关闭 SSL 证书验证（如果私有仓库使用自签名证书）
strict-ssl=false

# 认证信息：访问私有仓库时所需的用户名和密码（Base64 编码）
//your-private-registry-url/:_auth=your_base64_encoded_auth_token

⚠️ 注意：

替换 your-private-registry-url 为你公司的私有仓库地址。
your_base64_encoded_auth_token 是你的 Base64 编码的
username:password，格式必须正确。

📦 三、配置 hvigor-config.json5 文件（添加插件依赖）

✅ 路径：

bash 复制代码

your-project/
└── hvigor/
    └── hvigor-config.json5

✅ 内容：

json 复制代码

{
  "dependencies": {
    "@yourcompany/yourplugin": "^1.0.0"
  }
}

✅ 这一步告诉 HVIGOR 构建系统，你需要安装这个插件作为构建依赖。

🛠️ 四、配置 hvigorfile.ts 文件（导入并注册插件）

✅ 路径：

bash 复制代码

your-project/
└── hvigorfile.ts

✅ 内容示例：

ts 复制代码

import { appTasks } from '@ohos/hvigor-ohos-plugin';

// 导入私有插件
import { yourPluginFunction } from '@yourcompany/yourplugin';

export default {
  // 使用默认的 app 构建任务
  system: appTasks,

  // 注册插件，传入必要的参数（如 token 或配置对象）
  plugins: [
    yourPluginFunction('your_token_or_config')
  ]
}

✅ 根据插件定义的具体 API 修改导入名和调用方式。

🧪 五、清理缓存 & 重新构建项目

有时候旧缓存会导致问题，建议每次更改 .npmrc 或依赖后执行以下操作：

✅ 清理缓存：

删除路径：C:\Users\用户名.hvigor\project_caches*
或者在 DevEco 中点击菜单：Build > Clean Project

✅ 重新构建项目：

在 DevEco 中点击：Build > Rebuild Project

📌 六、常见问题排查

问题	可能原因	解决方案
安装失败 / 包找不到	`.npmrc` 配置错误	检查 `.npmrc` 是否存在、是否命名正确（带点）
插件未生效	`hvigorfile.ts` 没有注册插件	检查是否导入并调用了插件函数
认证失败	`_auth` 错误	检查 Base64 编码是否正确，联系管理员获取新 token
网络不通	私有仓库不可达	检查网络是否能访问私有仓库地址

📝 七、安全建议

.npmrc 中包含敏感信息（如 _auth 字段），请加入 .gitignore 避免提交到 Git 仓库。
不要随意分享 .npmrc 文件。
建议团队统一 .npmrc 模板，并通过内部文档说明使用方法。

✅ 总结一句话

在鸿蒙项目中使用私有 npm 插件，需要完成以下几步：

配置 .npmrc 设置私有仓库地址和认证信息
在 hvigor-config.json5 中声明插件依赖
在 hvigorfile.ts 中导入并注册插件
清理缓存后重新构建项目

鸿蒙应用开发： 鸿蒙项目中使用私有 npm 插件的完整流程