鸿蒙（HarmonyOS）Hvigor 构建插件：实现 HAR 模块 SNAPSHOT 版本自动替换时间戳

鸿蒙HarmonyOSHvigor 构建插件实现 HAR 模块 SNAPSHOT 版本自动替换时间戳前言在 HarmonyOS 项目开发中HAR 模块的版本管理是一个常见需求。如果你使用1.0.0-SNAPSHOT这类快照版本每次构建时手动改版本号非常麻烦。本文介绍一个零侵入的 Hvigor 插件只需在hvigorfile.ts中引入即可构建或运行时自动将 SNAPSHOT 版本号替换为毫秒时间戳如1.0.0-SNAPSHOT → 1.0.0-SNAPSHOT.1762827340027## 插件源码 在项目根目录的hvigor/目录下创建snapshot-version-plugin.ts文件typescript import * as fs from fs; import * as path from path; import { HvigorPlugin, HvigorNode } from ohos/hvigor; /** * 快照版本替换插件。 * * 功能说明 * 在 DevEco Studio 构建或运行 HAR 模块时自动将 oh-package.json5 中的 * SNAPSHOT 版本号替换为带毫秒时间戳的快照版本 * 1.0.0-SNAPSHOT → 1.0.0-SNAPSHOT.1762827340027 * 1.0.0-SNAPSHOT.1 → 1.0.0-SNAPSHOT.1762827340027 * 1.0.0-SNAPSHOT.12345 → 1.0.0-SNAPSHOT.1762827340027 * * 使用方式 * 在任意 HAR 模块的 hvigorfile.ts 中 * * import { snapshotVersionPlugin } from ../hvigor/snapshot-version-plugin; * * export default { * system: harTasks, * plugins: [snapshotVersionPlugin], * }; */ export const snapshotVersionPlugin: HvigorPlugin { // Hvigor 插件唯一标识 pluginId: snapshot-version-plugin, /** * Hvigor 插件入口模块加载时自动调用 * param node - HvigorNode 对象node.getNodePath() 返回模块根目录路径 */ apply(node: HvigorNode) { // 步骤 1获取当前模块的 oh-package.json5 路径 const modulePath node.getNodePath(); const packageJsonPath path.join(modulePath, oh-package.json5); // 步骤 2检查文件是否存在 if (!fs.existsSync(packageJsonPath)) { return; } // 步骤 3读取文件内容 const content fs.readFileSync(packageJsonPath, utf-8); // 步骤 4正则匹配 SNAPSHOT 版本号 // 匹配 version: x.y.z-SNAPSHOT 或 x.y.z-SNAPSHOT.N const snapshotPattern /version\s*:\s*([^]*-SNAPSHOT(?:\.[0-9])?)/; const match content.match(snapshotPattern); // 步骤 5替换为时间戳版本 if (match) { // 生成 13 位毫秒时间戳 const timestamp Date.now().toString(); // 替换 -SNAPSHOT.* → -SNAPSHOT.{timestamp} const newVersion match[1].replace(/-SNAPSHOT.*$/,-SNAPSHOT.${timestamp}); // 写回文件 const newContent content.replace(snapshotPattern,version:${newVersion});fs.writeFileSync(packageJsonPath,newContent,utf-8);}},};使用方式项目结构YourProject/├── hvigor/│ └── snapshot-version-plugin.ts ← 插件文件├── SnapShotHar/│ ├── hvigorfile.ts ← 引入插件│ └── oh-package.json5 ← 版本号 “1.0.0-SNAPSHOT”└── SnapShotHar2/├── hvigorfile.ts ← 同样引入└── oh-package.json5在模块中引入插件编辑 xxx.har模块/hvigorfile.tsimport{harTasks}fromohos/hvigor-ohos-plugin;import{snapshotVersionPlugin}from../hvigor/snapshot-version-plugin;exportdefault{system:harTasks,plugins:[snapshotVersionPlugin],// 注册插件};设置 har模块的oh-package.json5 版本号加上-SNAPSHOT{name:snapshothar,version:1.0.0-SNAPSHOT,description:Please describe the basic information.,main:Index.ets,author:,license:Apache-2.0,dependencies:{}}构建/运行在 DevEco Studio 中直接构建或运行该模块插件会自动触发oh-package.json5 中的版本号变为version:1.0.0-SNAPSHOT.1762827340027每次构建都会生成新的时间戳无需手动修改。工作原理步骤说明①Hvigor 加载模块 hvigorfile.ts调用 apply(node)②node.getNodePath() 获取模块根目录路径③拼接 oh-package.json5 完整路径④读取文件正则匹配 SNAPSHOT 版本号⑤生成 13 位毫秒时间戳替换版本号写回文件正则表达式说明/version\s*:\s*([^]*-SNAPSHOT(?:\.[0-9])?)/↑ ↑ 匹配SNAPSHOT可选匹配.N数字后缀适用场景多个 HAR 模块需要独立管理快照版本CI/CD 流水线中自动生成唯一版本号多人协作时避免版本号冲突注意事项1, 插件只在 oh-package.json5 存在时生效非 HAR 模块不受影响2, 每次构建/运行都会生成新的时间戳覆盖旧版本号3, 建议将 oh-package.json5 的初始版本号设为 1.0.0-SNAPSHOT不带 .N 后缀总结这个插件仅需一行 import 和一行 plugins 注册即可实现 HAR 模块的 SNAPSHOT 版本自动管理。代码简洁零侵入适合集成到任何 HarmonyOS 项目中。