鸿蒙（HarmonyOS）Hvigor 构建插件：实现 HAR 模块 SNAPSHOT 版本自动替换时间戳
鸿蒙（HarmonyOS）Hvigor 构建插件：实现 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.ts：
import{harTasks}from'@ohos/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 项目中。