安装

二次封装的启动命令,支持平台别名和自动生成配置

@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:

package.json
{
  "scripts": {
    "dev": "unh dev",
    "build": "unh build",
    "prepare": "unh prepare",
    "deploy": "unh deploy"
  }
}

在项目根目录放一个 unh.config.ts。不写也能运行。

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 完全一致:

unh.config.ts
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'

获取帮助

terminal
unh -h