UTS Plugin CLI

UTS 插件管理工具 - 从 GitHub/Gitee 仓库安装 uni-app 原生插件

功能特性

• 插件管理 - 安装、卸载、升级插件
• 插件搜索 - 按关键词搜索插件
• 插件详情 - 查看插件详细信息
• 外部文件关联 - 自动合并鸿蒙配置文件
• 双仓库支持 - 支持 GitHub 和 Gitee
• 智能降级 - 自动尝试多个下载源

安装

npm install -g @junerver/uts-plugin-cli

或者直接使用 npx：

npx @junerver/uts-plugin-cli <command>

使用方法

列出可用插件

npx @junerver/uts-plugin-cli list

安装插件

在 uni-app 项目根目录下执行：

npx @junerver/uts-plugin-cli install <plugin-name>

示例：

cd my-uni-app
npx @junerver/uts-plugin-cli install jkr-abc-epay

安装时如果插件包含外部文件（如鸿蒙配置文件），会提示选择处理方式：

• merge - 深度合并（推荐），智能合并配置项
• overwrite - 完全覆盖现有文件
• skip - 跳过不处理

使用 --force 参数可跳过交互提示，自动使用插件指定的默认策略：

npx @junerver/uts-plugin-cli install jkr-abc-epay --force

卸载插件

npx @junerver/uts-plugin-cli uninstall <plugin-name>

强制卸载（不提示确认）：

npx @junerver/uts-plugin-cli uninstall <plugin-name> --force

升级插件

npx @junerver/uts-plugin-cli update <plugin-name>

查看已安装插件

npx @junerver/uts-plugin-cli list --installed

搜索插件

npx @junerver/uts-plugin-cli search <keyword>

示例：

npx @junerver/uts-plugin-cli search epay

输出示例：

搜索结果：找到 1 个插件
仓库：junerver/UtsPlugins

  名称                    版本      描述
  ─────────────────────────────────────────────────────────
  jkr-abc-epay            1.0.4     农行e支付鸿蒙SDK封装，支持农行掌银支付功能

查看插件详情

npx @junerver/uts-plugin-cli info <plugin-name>

示例：

npx @junerver/uts-plugin-cli info jkr-abc-epay

输出示例：

插件详情
──────────────────────────────────────────────────

名称：jkr-abc-epay
版本：1.0.4
描述：农行e支付鸿蒙SDK封装，支持农行掌银支付功能
安装状态：未安装

包含文件：
  - changelog.md
  - package.json
  - readme.md
  - utssdk/app-harmony/index.uts
  ...

命令别名

| 命令 | 别名 | | ----------- | ---- | | install | i | | uninstall | rm | | update | u | | list | ls | | search | s |

示例：

npx @junerver/uts-plugin-cli i jkr-abc-epay
npx @junerver/uts-plugin-cli rm jkr-abc-epay
npx @junerver/uts-plugin-cli u jkr-abc-epay
npx @junerver/uts-plugin-cli ls
npx @junerver/uts-plugin-cli s epay
npx @junerver/uts-plugin-cli info jkr-abc-epay

仓库源配置

CLI 支持从 GitHub 或 Gitee 下载插件，默认自动选择（GitHub 优先）。

指定仓库源：

# 从 GitHub 获取（默认）
npx @junerver/uts-plugin-cli list --source github

# 从 Gitee 获取
npx @junerver/uts-plugin-cli list --source gitee

所有命令都支持 --source 参数：

npx @junerver/uts-plugin-cli install jkr-abc-epay --source gitee
npx @junerver/uts-plugin-cli search epay --source gitee
npx @junerver/uts-plugin-cli info jkr-abc-epay --source gitee

网络代理

如果无法访问 GitHub，可设置 HTTP 代理：

PowerShell

$Env:HTTPS_PROXY="http://127.0.0.1:7890"
npx @junerver/uts-plugin-cli list

CMD

set HTTPS_PROXY=http://127.0.0.1:7890
npx @junerver/uts-plugin-cli list

Linux/Mac

export HTTPS_PROXY=http://127.0.0.1:7890
npx @junerver/uts-plugin-cli list

插件来源

所有插件来自 GitHub 仓库：junerver/UtsPlugins

Gitee 镜像：junerver/UtsPlugins

CLI 通过读取仓库根目录的 plugins.json 文件获取插件列表和文件信息。

下载优先级

CLI 会按以下顺序尝试下载，成功后停止：

1. GitHub 直连 - raw.githubusercontent.com
2. GitHub 代理 - ghp.ci
3. GitHub 代理 - raw.gitmirror.com
4. Gitee - gitee.com

使用 --source 参数可强制指定仓库源（见 仓库源配置）。

自动化流程

UtsPlugins 仓库配置了 husky + pre-commit hook，每次提交时会自动：

1. 检测 uni_modules/ 目录是否有变更
2. 如果有变更，自动运行 scripts/generate-manifest.js
3. 更新 plugins.json 文件并添加到暂存区

开发者只需正常提交代码，plugins.json 会自动同步。

添加新插件

1. 在 uni_modules/ 目录下创建新插件
2. 正常提交代码
3. pre-commit hook 会自动更新 plugins.json

无需手动维护文件清单！

私有仓库

对于私有仓库，需要提供 GitHub token：

# 通过命令行参数
npx @junerver/uts-plugin-cli install jkr-abc-epay --token ghp_xxxx

# 通过环境变量
export GITHUB_TOKEN=*** npx @junerver/uts-plugin-cli install jkr-abc-epay

注意事项

1. 必须在 uni-app 项目根目录下执行安装命令（需要有 manifest.json 或 pages.json 文件）
2. 安装后的插件位于项目的 uni_modules/ 目录下
3. 使用插件时需要添加条件编译指令：

// #ifdef APP-HARMONY
import { xxx } from "@/uni_modules/plugin-name";
// #endif

外部文件关联

某些插件（如鸿蒙SDK插件）需要修改项目根目录下的配置文件。CLI支持声明外部关联文件，安装时自动处理合并。

目录结构

插件仓库中的目录结构：

uni_modules/jkr-abc-epay/
├── .uts-plugin.json          # 外部文件声明（可选）
├── _external/                # 外部文件存储目录（约定）
│   └── module.json5          # 外部配置文件片段
├── utssdk/                   # 插件自身文件
└── package.json

• _external 目录：约定的外部文件存储目录，不会收录到 files 中
• .uts-plugin.json：声明外部文件的处理规则
• 安装后会自动清理 _external 目录和 .uts-plugin.json 文件

配置格式

插件目录下创建 .uts-plugin.json 文件：

{
  "externalFiles": [
    {
      "source": "module.json5",
      "target": "harmony-configs/entry/src/main/module.json5",
      "strategy": "merge",
      "description": "配置ACL 受限权限",
      "arrayKeys": ["module.querySchemes"]
    }
  ]
}

字段说明

| 字段 | 说明 | |------|------| | source | 源文件路径（相对于插件的 _external 目录） | | target | 目标文件路径（相对于项目根目录） | | strategy | 默认处理策略：merge（合并）、overwrite（覆盖） | | description | 文件描述（可选） | | arrayKeys | 需要追加去重的数组键名（仅 merge 策略生效）。为空或不填时，合并全部字段 |

arrayKeys 说明

arrayKeys 支持嵌套路径，使用点号分隔：

{
  "arrayKeys": ["module.querySchemes"]
}

• "module.querySchemes"：表示 module 对象下的 querySchemes 数组需要去重追加
• 为空数组 [] 或不填时：所有数组字段都会去重追加

路径解析规则

| 字段 | 路径起点 | 示例 | |------|----------|------| | files[].path | 插件目录 | utssdk/app-harmony/config.json | | externalFiles[].source | 插件的 _external 目录 | module.json5 | | externalFiles[].target | 项目根目录 | harmony-configs/entry/src/main/module.json5 |

支持的配置文件

目前主要支持鸿蒙系统的 json5 格式配置文件：

1. /harmony-configs/oh-package.json5 - 项目依赖文件
2. /harmony-configs/build-profile.json5 - 数字签名配置
3. /harmony-configs/entry/src/main/module.json5 - ACL 权限配置
4. /harmony-configs/AppScope/app.json5 - 应用名称和版本信息

License

MIT