@uni-helper/unh 是 uni-app 命令的一层封装。它在 dev、build 前先生成 pages.json 与 manifest.json,再转发成 uni dev -p <platform>。
本包还提供平台别名、自定义 hooks、环境变量加载、开发者工具自动打开与小程序部署。
安装
npm i -D @uni-helper/unh本包只支持 ESM 项目。unh 启动时会检查当前目录最近一层 package.json 的 type 是否等于 module。不是时直接报错退出:
错误: 检测到当前项目为 CommonJS 环境,unh 仅支持 ESM 项目
请在 package.json 中添加 "type": "module" 后重试
解决的问题
uni 在 vite 配置阶段就读取磁盘上的 pages.json。只有一个页面时,它会关掉 __UNI_FEATURE_PAGES__,产物里不再包含 vue-router,页面跳转在运行时报错。
使用 vite-plugin-uni-pages 这类插件时,冷构建的磁盘上本来没有 pages.json,uni 读到的是占位内容。
unh 在 dev、build 之前,先在子进程里执行一次 vite 的 resolveConfig。这一步只触发插件初始化钩子,不进入打包阶段,让插件把真实的 pages.json、manifest.json、uni-pages.d.ts 写到磁盘。之后再执行 uni 命令。
预生成只在项目安装了 @uni-helper/vite-plugin-uni-pages 或 @uni-helper/vite-plugin-uni-manifest 时执行。生成失败只打印警告,不阻断命令。
使用
把 package.json 里的 uni 换成 unh:
{
"scripts": {
"dev": "unh dev",
"build": "unh build",
"prepare": "unh prepare",
"deploy": "unh deploy"
}
}
在项目根目录放一个 unh.config.ts。不写也能运行。
import { defineConfig } from '@uni-helper/unh'
export default defineConfig({
platform: {
// 不指定平台时用它
default: 'h5',
// 平台别名
alias: {
'h5': ['w', 'h'],
'mp-weixin': ['wx'],
},
},
env: true,
devtools: {
open: true,
},
})
pnpm dev wx
pages.json、manifest.json、uni-pages.d.ts 不用手动创建或提交。装了对应插件时,unh 会在 dev、build 前触发它们生成。
命令
| 命令 | 说明 |
|---|---|
unh dev [platform] | 开发。加载配置与环境变量,预生成配置文件,跑 hooks.dev,执行 uni dev -p <platform>,输出 ready in 后再跑 hooks.onDevAfter。 |
unh build [platform] | 构建。流程同上,走 hooks.build 与 hooks.onBuildAfter,同步等 uni build 结束。 |
unh prepare | 只跑 hooks.prepare,适合放在 package.json 的 prepare 脚本里。 |
unh deploy [targets] | 部署小程序构建产物,详见部署。 |
unh info | 用当前包管理器临时执行 @create-uni/info,打印项目信息。 |
unh platform | 用表格列出内置平台与说明。 |
unh -h、unh --version | 帮助信息与版本号。 |
省略 [platform] 时取 platform.default。写别名会先解析成完整平台名。
其余参数原样透传给 uni,所以 unh build mp-weixin --mode uat 等于 uni build -p mp-weixin --mode uat。
h5:ssr 例外:uni 的 SSR 是 --ssr 开关,没有这个平台,所以拼成 uni build -p h5 --ssr。
部署
unh deploy # 上传体验版(默认动作)
unh deploy wx # 指定平台,支持别名与逗号分隔
unh deploy preview wx # 指定动作:upload(默认)/ preview / open
| 动作 | 作用 |
|---|---|
upload | 上传代码作为体验版 |
preview | 上传代码作为开发版并生成预览二维码 |
open | 打开小程序开发者工具 |
可部署平台为 mp-weixin、mp-alipay、mp-toutiao、mp-baidu、mp-jd、mp-dingtalk。h5、mp-qq、mp-xhs 没有部署能力,传进去会报错。
常用选项:-p, --platform、-a, --action、--cwd、--config(传 false 表示不读配置文件)、--app-version、--desc、--project-path。
各平台官方的 CI 包是 @uni-helper/deploy 的可选 peer 依赖,按平台安装即可。例如微信小程序:
pnpm i -D miniprogram-ci
部署配置写在 unh.config.ts 的 deploy 字段下,字段与 @uni-helper/deploy 完全一致:
export default defineConfig({
deploy: {
'mp-weixin': {
appid: 'wx1234567890',
privateKeyPath: 'key/private.appid.key',
},
},
})
全部配置项、各平台字段与优先级见 @uni-helper/deploy 仓库。
API
defineConfig
function defineConfig(config: UniHelperConfig): UniHelperConfig
原样返回配置,作用是在 unh.config.ts 里获得类型提示。
类型
UniHelperConfig、HookOptions、PlatformAlias、CliPathConfig、ManifestOptions 从包入口导出:
import type { HookOptions, UniHelperConfig } from '@uni-helper/unh'
获取帮助
unh -h