鸿蒙Package Hook使用指南

 

一、Package Hook核心概念

 

1.1 什么是Package Hook

 

Package Hook是鸿蒙ohpm（OpenHarmony Package Manager）包管理器提供的生命周期钩子机制，基于项目根目录的oh-package.json5配置文件实现，能够在依赖安装、构建、版本管理、发布等关键节点，自动执行自定义脚本，实现工程流程自动化、依赖预处理、构建增强、环境适配等功能。

 

1.2 核心作用

 

- 自动化执行包管理全流程的自定义脚本，减少手动操作

 

- 动态处理依赖、资源文件、配置参数，适配多场景开发

 

- 统一团队工程规范，保障构建、发布流程一致性

 

- 实现依赖修复、资源拷贝、代码校验、版本锁定等自动化能力

 

1.3 支持的生命周期钩子

 

钩子名称

 

触发时机

 

核心适用场景

 

preInstall

 

执行ohpm install安装依赖前

 

环境校验、权限检查、依赖预校验

 

postInstall

 

依赖安装完成后

 

资源拷贝、补丁注入、配置生成、依赖修复

 

preUninstall

 

依赖卸载前

 

数据备份、关联资源清理

 

postUninstall

 

依赖卸载后

 

残留文件清理、工程状态重置

 

preVersion

 

执行ohpm version修改版本前

 

版本号规则校验、变更日志生成

 

postVersion

 

版本号修改完成后

 

同步版本至其他配置文件、版本信息上报

 

prePublish

 

执行ohpm publish发布前

 

代码校验、构建产物检查、签名处理

 

postPublish

 

包发布完成后

 

发布通知、部署同步、日志记录

 

1.4 关键约束

 

- 仅项目根目录的oh-package.json5支持配置hooks，模块级配置无效

 

- 脚本默认基于Node.js环境运行，支持JS/TS脚本、shell命令

 

- 系统仅执行当前工程自身钩子脚本，不执行第三方依赖包内的钩子，保障安全性

 

- 脚本返回非0退出码时，会直接中断当前ohpm命令执行

 

二、基础配置方式

 

2.1 极简配置（内嵌命令）

 

适合简单的命令执行场景，直接在oh-package.json5的hooks字段中编写命令：

 

// 项目根目录 oh-package.json5

{

  "name": "harmony-demo-app",

  "version": "1.0.0",

  "description": "鸿蒙Package Hook示例项目",

  "dependencies": {},

  "devDependencies": {},

  // 钩子配置

  "hooks": {

    "preInstall": "echo '开始检查依赖安装环境...'",

    "postInstall": "echo '依赖安装完成，执行初始化操作'",

    "prePublish": "echo '开始校验代码质量，准备发布'"

  }

}

 

2.2 推荐配置（独立脚本文件）

 

复杂逻辑建议编写独立脚本，便于维护和调试，步骤如下：

 

1. 创建脚本目录

 

项目根目录/

├── oh-package.json5

└── scripts/

    ├── pre-install.ts # 依赖安装前脚本

    ├── post-install.ts # 依赖安装后脚本

    └── build-utils.ts # 公共工具脚本

 

2. 编写钩子脚本（以post-install为例）

 

// scripts/post-install.ts

const fs = require('fs');

const path = require('path');

 

console.log('🔧 执行postInstall钩子：自动化处理资源');

 

// 示例：拷贝Web组件本地资源

const sourcePath = path.resolve(__dirname, '../assets/web/index.html');

const targetPath = path.resolve(__dirname, '../entry/src/main/resources/rawfile');

 

// 创建目标目录

if (!fs.existsSync(targetPath)) {

  fs.mkdirSync(targetPath, { recursive: true });

}

// 拷贝文件

fs.copyFileSync(sourcePath, path.join(targetPath, 'index.html'));

console.log('✅ Web资源自动拷贝完成');

 

// 脚本执行成功，退出码0

process.exit(0);

 

3. 配置脚本执行命令

 

// oh-package.json5

{

  "hooks": {

    "preInstall": "ts-node ./scripts/pre-install.ts",

    "postInstall": "ts-node ./scripts/post-install.ts"

  },

  // 开发依赖，用于执行TS脚本

  "devDependencies": {

    "ts-node": "^10.9.2",

    "typescript": "^5.3.3"

  }

}

 

三、高频实战场景

 

3.1 自动修复Web组件圆角问题

 

结合Web组件开发需求，在依赖安装后自动注入圆角样式：

 

// scripts/post-install.ts

const fs = require('fs');

const path = require('path');

 

// 定位Web组件文件

const webFilePath = path.resolve(__dirname, '../node_modules/@ohos/web/index.ets');

if (fs.existsSync(webFilePath)) {

  let fileContent = fs.readFileSync(webFilePath, 'utf-8');

  // 注入clip(true)和圆角样式，解决圆角不生效问题

  const injectStyle = `

    .borderRadius(20)

    .clip(true)

  `;

  // 替换Web组件原有代码，注入样式

  fileContent = fileContent.replace(/Web\(\{.*?\}\)\s*\{/s, `$&${injectStyle}`);

  fs.writeFileSync(webFilePath, fileContent);

  console.log('✅ Web组件圆角样式自动注入完成');

}

 

3.2 统一依赖版本，避免冲突

 

// oh-package.json5

{

  // 强制统一依赖版本

  "overrides": {

    "@ohos/common": "^2.1.0",

    "@ohos/web": "^1.2.0"

  },

  "hooks": {

    "preInstall": "echo '🔒 统一全局依赖版本，禁止版本冲突'"

  }

}

 

3.3 构建前自动生成配置文件

 

// scripts/pre-build.ts

const fs = require('fs');

const pkgInfo = require('../oh-package.json5');

 

// 生成构建配置文件

const buildConfig = {

  appName: pkgInfo.name,

  appVersion: pkgInfo.version,

  buildTime: new Date().toLocaleString(),

  env: process.env.BUILD_ENV || 'development'

};

 

// 写入配置文件

const outputPath = './entry/src/main/ets/utils/BuildConfig.ets';

const fileContent = `export const BuildConfig = ${JSON.stringify(buildConfig, null, 2)};`;

fs.writeFileSync(outputPath, fileContent);

console.log('📝 构建配置文件自动生成完成');

 

3.4 发布前代码质量校验

 

// oh-package.json5

{

  "hooks": {

    "prePublish": [

      "eslint ./entry/src --fix",

      "ohpm run test",

      "echo '✅ 代码校验、单元测试通过，准备发布'"

    ]

  }

}

 

四、与Hvigor构建钩子协同使用

 

Package Hook专注包管理生命周期，Hvigor构建钩子专注项目构建流程，两者配合可实现全流程自动化：

 

1. Package Hook触发构建任务

 

{

  "hooks": {

    "postInstall": "ohpm run build"

  }

}

 

2. Hvigor插件动态修改依赖配置

 

// hvigorfile.ts

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

 

export default {

  system: appTasks,

  plugins: [{

    pluginId: 'auto-modify-deps',

    apply(node) {

      const appContext = node.getContext('OHOS_APP_PLUGIN');

      const depsConfig = appContext.getDependenciesOpt();

      // 动态替换本地依赖

      depsConfig['@ohos/network'] = 'file:./libs/network.har';

      appContext.setDependenciesOpt(depsConfig);

    }

  }]

};

 

五、常见问题与避坑指南

 

5.1 钩子脚本不执行

 

- 检查配置文件：确认hooks配置在项目根目录的oh-package.json5

 

- 校验脚本路径：确保脚本文件路径、命令书写无误

 

- 查看详细日志：执行ohpm --verbose install查看执行日志，排查问题

 

- 检查依赖：执行TS脚本需安装ts-node和typescript依赖

 

5.2 脚本报错中断流程

 

- 脚本中添加异常捕获，避免意外中断：

 

try {

  // 执行业务逻辑

} catch (error) {

  console.error('❌ 钩子执行失败：', error);

  process.exit(1);

}

 

5.3 修改node_modules被覆盖

 

- 将依赖修改逻辑写入postInstall钩子，每次安装依赖自动执行

 

- 推荐使用patch-package生成补丁，持久化第三方依赖修改

 

5.4 跨平台脚本兼容问题

 

- 避免直接使用系统专属命令，优先使用Node.js原生API编写脚本

 

- Windows系统可通过cmd /c "命令"执行，Mac/Linux直接使用shell命令