1. 为什么你需要工程化开发 Hvigor 插件如果你正在开发鸿蒙应用肯定对 Hvigor 不陌生。它就像鸿蒙项目的“大管家”编译、打包、签名这些脏活累活都归它管。但用久了你会发现官方提供的构建流程有时不够用。比如你想在编译前自动检查代码规范想在打包后把产物自动上传到内网服务器或者团队里有一套通用的资源压缩流程每个新项目都想复用。这时候你就需要自己动手写 Hvigor 插件了。我刚开始接触插件开发时也图省事直接把代码写在项目的hvigorfile.ts里。这招快是快但很快就遇到了麻烦。当第二个、第三个项目也需要同样的功能时我只能复制粘贴代码。后来团队里其他人也要用我光是通过聊天软件发代码片段就发了无数次版本还经常对不上维护起来简直是噩梦。直到我把插件改造成一个独立的 TypeScript 项目并发布到内部的 npm 仓库所有问题才迎刃而解。现在任何同事只需要在配置文件里加一行依赖就能用上最新、最稳定的插件功能。所以这篇文章要聊的就是这条更高级、也更实用的路如何用 TypeScript 工程化的方式从零开发一个专业的 Hvigor 插件并把它发布成 npm 包。这不仅仅是“怎么写代码”更是“怎么设计项目结构”、“怎么管理依赖”、“怎么让团队协作更顺畅”的完整解决方案。无论你是想提升个人项目的自动化水平还是为团队打造一套高效的构建工具链这套流程都值得你花时间掌握。2. 工程化第一步搭建专业的 TypeScript 插件项目很多教程一上来就让你写代码但我认为一个好的开始是成功的一半。搭建一个结构清晰、配置合理的项目能让你在后续开发、调试和发布中省去无数麻烦。这里我会带你一步步创建一个“标准范儿”的插件项目。2.1 初始化项目不仅仅是npm init首先为你的插件创建一个独立的目录。别在现有的鸿蒙工程里凑合独立的项目意味着独立的版本管理和依赖控制。# 创建一个项目文件夹名字建议和将来要发布的npm包名一致 mkdir harmony-custom-plugin cd harmony-custom-plugin接下来执行npm init初始化项目。这里有几个细节需要注意它们会影响后续的发布和使用体验npm init执行命令后你会被问到一系列问题。除了package name包名和version版本是必填且重要的其他的如description描述、keywords关键词也请认真填写这能帮助别人在 npm 上找到你的插件。entry point入口文件我强烈建议填写dist/index.js而不是src/index.ts。这是因为我们最终发布到 npm 的是编译后的 JavaScript 文件dist目录是行业惯例指向编译后的输出。初始化完成后你会得到一个package.json文件。我们先别急着写代码对它进行一轮“增强”{ name: harmony-clean-temp-plugin, version: 1.0.0, description: 一个用于鸿蒙项目的Hvigor插件提供构建时自动清理临时文件等功能。, main: dist/index.js, types: dist/index.d.ts, scripts: { build: tsc, prepublishOnly: npm run build }, keywords: [harmonyos, hvigor, plugin, build-tool], author: Your Name, license: MIT, devDependencies: { types/node: ^20.0.0, typescript: ^5.0.0 }, dependencies: { ohos/hvigor: 5.2.2 }, files: [dist, README.md] }我在这里做了几处关键改动增加了types字段指向dist/index.d.ts。这能为使用你插件的开发者提供完美的 TypeScript 类型提示体验极佳。优化了scriptsbuild命令用于编译 TypeScriptprepublishOnly是一个 npm 生命周期钩子它会在执行npm publish之前自动运行build确保每次发布的内容都是最新的编译结果。明确了files字段这个数组定义了哪些文件会被包含在发布的 npm 包中。通常只包含编译后的dist目录和说明文档避免把源码、测试文件等无关内容发布出去让包更精简。2.2 配置 TypeScript为鸿蒙环境量身定制接下来生成 TypeScript 配置文件npx tsc --init这会生成一个tsconfig.json文件。默认配置可用但为了开发 Hvigor 插件更顺手我建议你进行如下调整{ compilerOptions: { target: ES2017, module: commonjs, declaration: true, outDir: ./dist, rootDir: ./src, strict: true, esModuleInterop: true, skipLibCheck: true, forceConsistentCasingInFileNames: true, resolveJsonModule: true }, include: [src/**/*], exclude: [node_modules, dist] }重点解释几个配置declaration: true在编译时自动生成.d.ts类型声明文件这就是上面package.json中types字段的源头。outDir: ./dist和rootDir: ./src这建立了清晰的源码src和输出dist目录结构。resolveJsonModule: true允许在 TypeScript 中直接导入 JSON 文件。如果你的插件需要读取一些配置文件这个选项会非常有用。2.3 解决依赖安装的核心难题配置 npm 镜像这是新手最容易卡住的一步。鸿蒙的ohos/hvigor包并不在 npm 官方仓库里如果你直接npm install肯定会得到一个 404 错误。解决方法是在你的用户目录下配置一个.npmrc文件。这个文件的作用是指定 npm 从哪里下载包。找到你的用户目录Windows:C:\Users\你的用户名Mac/Linux:/Users/你的用户名或/home/你的用户名创建或编辑.npmrc文件注意文件名以点开头是个隐藏文件。用任何文本编辑器打开它添加以下内容# 默认仓库使用华为云镜像加速普通包的下载 registryhttps://repo.huaweicloud.com/repository/npm/ # 所有以 ohos 开头的包都从鸿蒙官方仓库下载 ohos:registryhttps://repo.harmonyos.com/npm/这个配置是分层解析的当你安装lodash时npm 会去华为云镜像找当你安装ohos/hvigor时npm 则会自动切换到鸿蒙的专属仓库。配置好后回到你的插件项目目录执行安装命令# 安装开发依赖TypeScript编译器及Node.js类型定义 npm install --save-dev typescript types/node # 安装生产依赖Hvigor核心库 npm install --save ohos/hvigor看到node_modules文件夹被成功创建并且里面包含了ohos目录就说明镜像配置成功依赖安装无误。3. 从零编写一个具备实用价值的插件项目架子搭好了现在我们来开发一个真正有用的插件。我们不止实现一个简单的“Hello World”而是做一个构建时自动清理临时文件的插件并为其添加可配置选项让它更灵活、更专业。3.1 设计插件接口与核心逻辑首先在src目录下创建我们的插件主文件src/clean-temp-plugin.ts。一个好的插件应该考虑可配置性所以我们先定义一个配置项接口。// src/clean-temp-plugin.ts import { HvigorNode, HvigorPlugin } from ohos/hvigor; import fs from fs; import path from path; // 定义插件的配置选项接口 export interface CleanTempPluginOptions { // 要清理的目录名称默认为 temp targetDirName?: string; // 是否在清理前进行确认提示用于安全默认为 false enableConfirm?: boolean; // 可以扩展其他选项比如忽略列表等 } /** * 创建一个清理临时目录的Hvigor插件 * param options 插件配置选项 * returns HvigorPlugin实例 */ export function createCleanTempPlugin(options: CleanTempPluginOptions {}): HvigorPlugin { // 合并默认配置和用户传入的配置 const finalOptions: RequiredCleanTempPluginOptions { targetDirName: temp, enableConfirm: false, ...options, }; return { pluginId: harmony-clean-temp-plugin, // 插件唯一ID apply(node: HvigorNode) { // 1. 基础信息打印 console.log( [${this.pluginId}] 插件已加载到节点: ${node.nodeName}); // 2. 核心清理逻辑 const targetDirPath path.join(node.projectPath, finalOptions.targetDirName); // 定义一个清理函数 const cleanDirectory () { if (fs.existsSync(targetDirPath)) { try { fs.rmSync(targetDirPath, { recursive: true, force: true }); console.log(✅ 成功清理目录: ${targetDirPath}); } catch (error: any) { console.error(❌ 清理目录失败: ${error.message}); } } else { console.log(ℹ️ 目录不存在无需清理: ${targetDirPath}); } }; // 3. 根据配置决定执行方式 if (finalOptions.enableConfirm) { // 模拟一个“确认”环节在实际中你可能需要更复杂的交互逻辑 console.log(⚠️ 即将清理目录: ${targetDirPath} (此操作不可逆)); // 这里可以集成更复杂的确认机制例如读取环境变量 // 为了示例我们假设环境变量 CONFIRM_CLEANtrue 时执行 if (process.env.CONFIRM_CLEAN true) { cleanDirectory(); } else { console.log(⏸️ 已跳过清理未确认); } } else { // 默认直接执行清理 cleanDirectory(); } // 4. 注册一个自定义任务供开发者手动调用 node.addTask({ taskName: clean${finalOptions.targetDirName.charAt(0).toUpperCase() finalOptions.targetDirName.slice(1)}Dir, // 动态生成任务名如 cleanTempDir taskType: CUSTOM, doTask: async () { console.log( 开始执行手动清理任务...); cleanDirectory(); return true; }, }); }, }; }这个插件比简单的打印日志高级在哪里可配置化通过options参数使用者可以自定义要清理的目录名以及是否启用安全确认。这大大提升了插件的灵活性。逻辑封装将核心的清理逻辑抽离成cleanDirectory函数使apply方法更清晰也便于在自定义任务中复用。动态任务名根据配置的targetDirName动态生成自定义任务的名称例如cleanTempDir或cleanCacheDir非常巧妙。环境变量集成展示了如何通过环境变量CONFIRM_CLEAN来控制插件行为这在 CI/CD 流水线中非常实用。3.2 创建项目入口并编译插件逻辑写好了我们需要创建一个入口文件来导出它。在src目录下创建index.ts// src/index.ts export { createCleanTempPlugin, CleanTempPluginOptions } from ./clean-temp-plugin; // 可以在这里导出多个插件函数 // export { anotherPlugin } from ./another-plugin;现在执行编译命令将 TypeScript 代码转换为 JavaScriptnpm run build执行成功后你会看到项目根目录下生成了一个dist文件夹里面包含了编译后的index.js、index.d.ts以及clean-temp-plugin.js、clean-temp-plugin.d.ts文件。.d.ts文件就是为使用者提供类型提示的宝贝。3.3 本地测试如何在不发布的情况下验证插件在发布到 npm 之前我们肯定要先在本地测试插件是否工作正常。有两种非常方便的方法方法一使用npm link推荐在你的插件项目根目录执行npm link这会在全局 npm 空间中创建一个到你当前项目的符号链接。切换到你的鸿蒙应用项目根目录执行npm link harmony-clean-temp-plugin这会在鸿蒙项目的node_modules中创建一个指向你插件开发目录的链接。之后你就可以在鸿蒙项目的hvigorfile.ts中像使用已发布的包一样导入并测试你的插件了。修改插件代码后只需在插件项目重新执行npm run build鸿蒙项目就能立即用到最新版本。方法二使用本地文件路径在你的鸿蒙项目的hvigor/hvigor-config.json5中直接通过file:协议引用本地插件目录{ schemaVersion: 2.0.0, dependencies: { harmony-clean-temp-plugin: file:/path/to/your/harmony-clean-temp-plugin } }然后执行hvigorw --sync同步依赖。这种方法同样可以实现即时修改、即时生效但路径是绝对路径不利于团队共享。4. 发布到 npm 仓库让插件可以被所有人使用本地测试通过后就可以考虑发布了。你可以发布到公司私有仓库、华为云提供的仓库或者 npm 官方仓库。4.1 发布前的最终检查与配置发布前请再次确认以下几点版本号确保package.json中的version字段是新的且符合语义化版本规范如1.0.1。.npmignore文件与package.json中的files字段作用类似用于排除不想发布的文件。通常需要忽略src/,test/,.git/等。一个简单的.npmignore内容如下src/ test/ .gitignore .editorconfig tsconfig.json *.logREADME.md编写一个清晰的说明文档至少包含插件简介、安装方式、使用方法、配置选项和示例。这是项目的门面。切换发布源如果你要发布到私有仓库需要将用户目录下.npmrc文件中的registry改为你的私有仓库地址。如果要发布到 npm 官方可以执行npm config set registry https://registry.npmjs.org/。4.2 执行发布命令首先你需要登录到对应的 npm 仓库npm login按照提示输入用户名、密码和邮箱。然后执行发布命令npm publish如果看到类似 harmony-clean-temp-plugin1.0.0的输出恭喜你发布成功了4.3 在其他鸿蒙项目中使用已发布的插件现在其他开发者就可以像使用任何其他 npm 包一样使用你的插件了。添加依赖在目标鸿蒙项目的hvigor/hvigor-config.json5文件中添加依赖。{ schemaVersion: 2.0.0, dependencies: { harmony-clean-temp-plugin: ^1.0.0 // 使用语义化版本范围 } }安装依赖在项目根目录执行同步命令。# Windows hvigorw --sync # Mac/Linux ./hvigorw --sync导入并使用在需要应用插件的模块如app/hvigorfile.ts中导入并启用。// app/hvigorfile.ts import { appTasks } from ohos/hvigor; import { createCleanTempPlugin } from harmony-clean-temp-plugin; export default { system: appTasks, plugins: [ // 使用默认配置 // createCleanTempPlugin(), // 或使用自定义配置 createCleanTempPlugin({ targetDirName: build-cache, // 清理名为 build-cache 的目录 enableConfirm: true, // 启用确认需设置环境变量 CONFIRM_CLEANtrue 才会执行 }), ], };验证效果运行任意 Hvigor 命令如hvigorw tasks你将在配置阶段看到插件的日志输出。你也可以直接运行插件注册的自定义任务例如hvigorw cleanBuildCacheDir。5. 进阶实战开发一个代码规范检查插件掌握了基础流程后我们来挑战一个更复杂的实战案例开发一个在构建前自动执行代码规范检查例如使用 ESLint的插件。这个例子会涉及更复杂的 Node.js 子进程操作和任务依赖管理。5.1 设计思路与项目初始化这个插件的目标是在项目执行编译任务如compile之前自动运行 ESLint 检查代码。如果检查不通过则终止构建流程。首先为新插件创建一个新项目或在上一个项目中新增一个插件文件。我们需要安装 ESLint 作为开发依赖注意这里是插件项目的依赖不是鸿蒙项目的。# 在你的插件项目目录下 npm install --save-dev eslint types/eslint # 安装常用的ESLint配置这里以标准配置为例 npm install --save-dev eslint-config-standard eslint-plugin-import eslint-plugin-node eslint-plugin-promise5.2 实现插件核心逻辑创建文件src/eslint-check-plugin.ts// src/eslint-check-plugin.ts import { HvigorNode, HvigorPlugin, Task } from ohos/hvigor; import { ESLint } from eslint; import path from path; export interface ESLintCheckPluginOptions { // 要检查的文件扩展名默认为 [.ts, .js] extensions?: string[]; // ESLint配置文件的路径默认为项目根目录的 .eslintrc.js configFile?: string; // 是否在控制台输出详细的ESLint结果 verbose?: boolean; } export function createESLintCheckPlugin(options: ESLintCheckPluginOptions {}): HvigorPlugin { const finalOptions { extensions: [.ts, .js], configFile: .eslintrc.js, verbose: false, ...options, }; return { pluginId: harmony-eslint-check-plugin, apply(node: HvigorNode) { console.log( [${this.pluginId}] 代码规范检查插件已启用); // 关键修改已有的编译任务为其添加一个前置依赖任务 // 1. 首先找到名为 compile 的任务假设这是编译任务 const compileTask node.getTaskByName(compile); if (compileTask) { // 2. 创建一个ESLint检查任务 const eslintTask: Task { taskName: runESLintCheck, taskType: CUSTOM, doTask: async () { console.log( 开始执行代码规范检查...); try { const eslint new ESLint({ useEslintrc: false, // 不使用项目中的.eslintrc.*文件 overrideConfigFile: path.resolve(node.projectPath, finalOptions.configFile), extensions: finalOptions.extensions, cwd: node.projectPath, // 以项目根目录为工作目录 }); // 对项目src目录下的文件进行检查 const results await eslint.lintFiles([src/**/*.{ts,js}]); const formatter await eslint.loadFormatter(stylish); const resultText formatter.format(results); if (finalOptions.verbose) { console.log(resultText); } // 判断是否有错误 const hasError results.some(result result.errorCount 0); if (hasError) { console.error(❌ ESLint检查发现错误构建终止。); console.log(resultText); // 出错时强制输出详情 return false; // 返回false表示任务失败会阻止依赖它的任务如compile执行 } else { console.log(✅ 代码规范检查通过); return true; } } catch (error: any) { console.error(❌ ESLint检查过程出错: ${error.message}); return false; } }, }; // 3. 将ESLint检查任务添加到节点 node.addTask(eslintTask); // 4. 修改compile任务使其依赖于eslintTask // 注意Hvigor API可能需要通过特定方式修改任务依赖这里是一种常见思路 // 实际情况可能需要查阅最新Hvigor文档或通过其他Hook实现 // 假设我们可以通过扩展任务配置来实现 compileTask.dependsOn [...(compileTask.dependsOn || []), runESLintCheck]; console.log(✅ 已将ESLint检查任务设置为 compile 的前置条件); } else { console.warn(⚠️ 未找到 compile 任务ESLint检查插件可能未正确挂载。); } }, }; }5.3 处理复杂的任务依赖与错误传递上面的代码展示了核心思路拦截并修改现有的构建任务。在实际的 Hvigor 插件开发中操作任务依赖链是高级但强大的功能。你需要仔细阅读 Hvigor 的官方 API 文档了解如何安全地获取和修改任务对象。一种更稳健的做法可能是利用 Hvigor 提供的生命周期钩子在任务执行前插入你的检查逻辑。这个进阶案例的意义在于它跳出了简单的“打印日志”和“文件操作”开始与构建流程的核心——任务系统进行交互。通过开发这样的插件你可以实现代码质量门禁自动化测试构建产物分析自定义资源处理流水线将你的构建流程完全掌控在自己手中。6. 工程化开发的持续维护与最佳实践插件发布出去只是开始如何长期维护它让它易于使用和协作才是工程化的真正考验。1. 版本管理策略严格遵守语义化版本SemVer规范主版本号.次版本号.修订号。修订号向后兼容的问题修复递增它。次版本号向后兼容的功能性新增递增它并将修订号归零。主版本号发生了不兼容的 API 变更递增它并将次版本号和修订号归零。 在package.json中为使用者提供合理的版本范围如^1.0.0表示兼容1.x.x的最新版本。2. 完善的文档与示例一个README.md至少应包括简介与特性安装指南快速开始一个最简单的使用示例详细的配置选项说明API 文档如果插件提供了多个函数或类常见问题FAQ贡献指南 在项目中建立一个examples目录存放不同使用场景的示例代码这是最好的文档。3. 引入单元测试为你的插件逻辑编写单元测试。使用 Jest、Mocha 等测试框架。这不仅能保证代码质量在后续修改功能时也能给你巨大的信心。在package.json中添加测试脚本scripts: { test: jest, build: tsc, prepublishOnly: npm run test npm run build }这样在发布前会自动运行测试确保不会把有问题的代码发布出去。4. 利用 GitHub Actions 或 GitLab CI 实现自动化配置 CI/CD 流水线实现代码推送后自动运行测试、自动编译、并在打上 Git Tag 时自动发布到 npm 仓库。这能极大提升协作效率和发布质量。从在hvigorfile.ts里写几行脚本到建立一个拥有完整测试、文档和自动化流程的 TypeScript 插件项目这个转变带来的不仅是代码的复用更是开发理念的升级。你会开始像维护一个产品一样去维护你的工具思考它的 API 设计、用户体验和长期演进。当团队里的新成员也能通过一句npm install就获得你积累的最佳实践时这种工程化带来的价值就真正体现出来了。