鸿蒙（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');
    }
  },
};

使用方式

1. 项目结构
   YourProject/
   ├── hvigor/
   │ └── snapshot-version-plugin.ts ← 插件文件
   ├── SnapShotHar/
   │ ├── hvigorfile.ts ← 引入插件
   │ └── oh-package.json5 ← 版本号 “1.0.0-SNAPSHOT”
   └── SnapShotHar2/
   ├── hvigorfile.ts ← 同样引入
   └── oh-package.json5

2. 在模块中引入插件：
   编辑 xxx.har模块/hvigorfile.ts：

import { harTasks } from '@ohos/hvigor-ohos-plugin';
import { snapshotVersionPlugin } from '../hvigor/snapshot-version-plugin';

export default {
  system: harTasks,
  plugins: [snapshotVersionPlugin],  // 注册插件
};

3. 设置 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": {}
}

4. 构建/运行
   在 DevEco Studio 中直接构建或运行该模块，插件会自动触发，oh-package.json5 中的版本号变为：

"version": "1.0.0-SNAPSHOT.1762827340027"

每次构建都会生成新的时间戳，无需手动修改。

工作原理

正则表达式说明：

/"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 项目中。