Astron RPA 插件开发 CLI 完全指南:从 `@rpa/cli` 安装、脚手架生成到 Module Federation 构建实战
Astron RPA 插件开发 CLI 完全指南:从 @rpa/cli 安装、脚手架生成到 Module Federation 构建实战
导读
@rpa/cli 是 Astron RPA(astron-rpa)前端插件体系的命令行工具,负责插件模板脚手架生成、开发服务器启动与生产构建。本文以 frontend/packages/cli/README.zh-CN.md 为主体,结合仓库中 src/cli、templates/template-vue、@rpa/shared 及 Web 端 PluginManager 的源码实现,完整讲解 CLI 的安装方式、三大核心命令(dev / build / create)的用法与底层原理、全局选项的调试技巧,以及如何用 rpa create 生成一个可被 Astron RPA 客户端动态加载的插件,最终带你打通"开发 → 构建 → 宿主加载"的完整链路。
背景:为什么 Astron RPA 需要一套插件 CLI
Astron RPA 前端采用 pnpm monorepo 结构(见 frontend/package.json),其中 packages/cli(即 @rpa/cli)、packages/shared(@rpa/shared,提供插件类型与 definePlugin)与 packages/web-app(宿主应用)相互协作。插件通过 Module Federation 以远程模块形式加载:CLI 负责把插件源码构建成"remote",宿主端 PluginManager 再通过 @module-federation/enhanced/runtime 的 loadRemote 动态拉取并激活插件。
因此 @rpa/cli 并不是一个通用的脚手架工具,而是 Astron RPA 插件开发生命周期(创建、开发、构建)的专用入口。它的可执行文件名为 rpa,在 package.json 中通过 "bin": { "rpa": "./bin/rpa.js" } 暴露。
一、安装 @rpa/cli
CLI 支持全局安装与项目本地安装两种方式,包管理器可选 npm 或 pnpm。
# 全局安装
npm install -g @rpa/cli
# 或
pnpm add -g @rpa/cli
# 本地安装
npm install @rpa/cli --save-dev
# 或
pnpm add @rpa/cli -D
环境前提:仓库根目录 frontend/package.json 声明
"engines": { "node": ">=22", "pnpm": ">=9" },并在preinstall中强制使用 pnpm(npx only-allow pnpm)。如果你是进入仓库开发,请先满足该 Node/pnpm 版本要求;在独立项目中使用时,同样建议使用 Node 22+ 以获得 Vite 7 与@module-federation/vite的完整支持。
在仓库内本地开发时,推荐在 packages/cli 目录先执行 pnpm install,再运行 pnpm build 生成 dist 产物后使用。
二、三大核心命令详解
CLI 的命令解析基于 cac 实现,全部命令定义在 src/cli/commands.ts 中:
const cli = cac('rpa')
cli.help().version(version)
cli.option('--debug [feat]', 'Show debug logs')
cli.command('dev', 'Start the development server')...
cli.command('build', 'build the library for production')...
cli.command('create', 'create a plugin template')...
2.1 rpa dev —— 启动开发服务器
rpa dev
该命令用于插件开发调试。执行后,源码中会调用 createBuildServer({ dev: true }),其内部逻辑(见 src/cli/vite.ts)为:
- 以当前工作目录为根,调用
loadRpaConfig(root, 'serve', 'development')读取用户配置; - 组装 Vite
InlineConfig,注入@module-federation/vite的federation插件、@vitejs/plugin-vue与@vitejs/plugin-vue-jsx; - 配置
exposes: { './index': './src/index.ts' },即插件入口统一暴露为模块名/index; - 以
development模式创建并启动 Vite Dev Server,调用viteServer.printUrls()打印访问地址,并绑定 CLI 快捷键(bindCLIShortcuts)。
开发模式下 publicPath 不设置(使用 Vite 默认路径),因此 HMR 与本地调试都走标准 Vite 链路。你可以直接修改 src/ 下的 Vue 组件与 TS 文件,浏览器/宿主端即可热更新。
2.2 rpa build —— 构建生产库
rpa build
# 带监听模式构建
rpa build --watch
选项:
| 选项 | 说明 |
|---|---|
-w, --watch |
开启监听模式,监听文件变化并自动重新构建 |
构建时 createBuildServer({ dev: false }) 会以 'build' 命令、production 模式执行:
- 同样读取
rpa.config.ts等用户配置,取userConfig?.name || 'remote'作为远程模块名remoteName; - 关键差异在于
publicPath被显式设置为`rpa://extensions/${remoteName}/`,并开启manifest: true——这正是插件产物被 Astron RPA 客户端识别、安装与加载的约定路径协议; - 最终调用 Vite 的
build()产出生产包。构建配置里还设置了build.modulePreload = false,并让vue、vue-router作为共享依赖(shared: ['vue', 'vue-router']),避免宿主与插件重复打包框架代码。
--watch 模式对应构建层级的监听(-w),适合持续迭代产物文件;日常交互式开发请优先使用 rpa dev。
2.3 rpa create —— 脚手架生成插件模板
rpa create
# 或指定参数
rpa create --name my-plugin --target ./packages/my-plugin
选项:
| 选项 | 说明 |
|---|---|
-n, --name [name] |
插件名称 |
-t, --target [dir] |
生成的目标目录 |
若未提供选项,rpa create 会启动基于 @clack/prompts 的交互式引导:
- 提示输入插件名称(默认值/占位符为
my-plugin); - 提示输入目标目录(默认值为
path.resolve(cwd, 'packages/<name>')); - 若用户中途按 Esc/Ctrl+C 取消(
isCancel),输出Operation cancelled并退出。
非交互模式下,命令会依次做以下校验与操作(见 src/cli/commands.ts 的 create action):
- 调用
getBuiltinTemplateDir()定位内置模板目录(源码解析见 src/utils.ts 的path.resolve(dirname, '../templates/template-vue')),模板即仓库中的 templates/template-vue; - 将目标目录的 Windows 反斜杠统一替换为正斜杠(
targetDir.replace(/\\+/g, '/')); - 若目标目录已存在,输出
target directory already exists并终止,防止覆盖; - 递归创建目录后调用
renderTemplate(templateDir, target, { name })完成渲染; - 完成后输出
plugin template created at <目标目录>。
renderTemplate(见 src/utils.ts)的处理细节值得一提:
- 遍历模板目录时跳过
node_modules与dist; - 文件/目录名中的
{{name}}占位符会被替换为插件名; - 二进制文件(png/jpg/jpeg/gif/svg/ico/webp)直接拷贝;
- 文本文件用 EJS 渲染(
ejs.render(content, data)),渲染失败时回退为纯文本拷贝并打印警告——所以模板里的<%= name %>这类 EJS 占位符最终会替换成真实插件名。
三、全局选项与调试日志
所有命令均支持以下全局选项:
--debug [feat]:显示调试日志(feat为可选的调试命名空间);--help:显示帮助信息;--version:显示版本号。
--debug 的底层实现位于 src/cli/commands.ts 的 runCli() 中:它基于 debug 库启用命名空间。
if (cli.options.debug === true) {
namespace = 'rpa:*' // 全部命名空间
}
else {
// 支持逗号分隔的多个特性
namespace = resolveComma(toArray(cli.options.debug))
.map(v => `rpa:${v}`)
.join(',')
}
debug.enable(namespace)
也就是说:
rpa dev --debug启用全部rpa:*调试日志;rpa dev --debug vite只启用rpa:vite命名空间;rpa dev --debug vite,config可同时启用多个命名空间(逗号分隔)。
日志输出由 src/logger.ts 提供分级支持(silent/error/warn/info),错误会以红色 ERROR 前缀输出;命令执行失败时 runCli 会捕获异常、记录日志并以退出码 1 结束进程。
四、配置文件 rpa.config.ts 与 defineConfig
CLI 遵循 Vite 的配置加载约定。loadRpaConfig(见 src/config.ts)会依次探测以下文件名并加载第一个存在的配置:
rpa.config.ts
rpa.config.js
rpa.config.mjs
rpa.config.cjs
rpa.config.mts
rpa.config.cts
配置类型 RpaConfig 即 @module-federation/vite 中 federation 插件的参数类型。CLI 对外导出 defineConfig 辅助函数(也支持传入 Promise 或函数形式),用于提供类型提示:
import { defineConfig } from '@rpa/cli'
export default defineConfig({
name: 'my-plugin',
})
实际构建时(src/cli/vite.ts),用户配置会被展开进 federation({ shared: ['vue', 'vue-router'], ...userConfig, name: remoteName, manifest: true, publicPath: ... }),并固定暴露 './index'。因此你的 rpa.config.ts 中至少应保证 name 与产物构建要求一致,其他 Module Federation 选项(如 remotes、exposes 扩展、shared 调整)也可按需覆盖。
五、亲手跑一个插件:从 rpa create 到宿主加载
5.1 生成模板
rpa create --name hello-rpa --target ./packages/hello-rpa
生成后的目录结构大致如下(对应仓库中的 templates/template-vue):
packages/hello-rpa/
├── package.json # name 已被替换为 hello-rpa,含 dev/build 脚本
├── rpa.config.ts # export default defineConfig({ name: 'hello-rpa' })
├── tsconfig.json
├── index.html
└── src/
├── index.ts # definePlugin 入口
├── main.ts # 本地调试挂载
└── Content.vue # 设置页 Tab 组件
模板自带的 package.json 直接内置了两条命令,让你无需记忆 CLI 细节:
"scripts": {
"dev": "rpa dev",
"build": "rpa build"
}
5.2 理解模板入口 src/index.ts
模板入口使用 @rpa/shared 提供的 definePlugin 与 IPluginContext:
import type { IPluginContext } from '@rpa/shared'
import { definePlugin } from '@rpa/shared'
import { markRaw } from 'vue'
import Content from './Content.vue'
export default definePlugin({
activate: async (_context: IPluginContext) => {
console.log('[SimplePluginExample] 插件激活中...')
},
deactivate: () => {
console.log('[SimplePluginExample] 插件停用中...')
console.log('[SimplePluginExample] 插件停用完成')
},
contributes: {
settingsTabs: [
{
id: 'text',
title: '测试',
icon: 'plugin',
content: markRaw(Content),
},
],
},
})
其类型契约定义在 frontend/packages/shared/src/types/plugin.ts:IPluginModule 由 activate(激活)、deactivate(停用)与 contributes(贡献点)组成;当前模板演示了 settingsTabs 这一贡献点——往客户端"设置"页注册一个 Tab,其中 content 必须是 Vue 组件(用 markRaw 包裹避免被响应式代理)。definePlugin 本身只是一个类型化辅助函数(见 frontend/packages/shared/src/core/plugins.ts)。
依赖说明:模板
package.json依赖@rpa/shared(workspace 包)。在独立仓库外使用模板时,请将"@rpa/shared": "workspace:*"替换为实际可发布的版本号。
5.3 开发与构建
cd packages/hello-rpa
pnpm install
pnpm dev # 启动开发服务器,等同 rpa dev
pnpm build # 生产构建,等同 rpa build
构建完成后,产物的远程模块名由 rpa.config.ts 的 name 决定,入口模块路径为 ./index,publicPath 指向 rpa://extensions/<name>/,并生成 Module Federation manifest——这组约定正是宿主端加载插件所依赖的协议。
5.4 宿主端如何加载:PluginManager 侧写
Astron RPA Web 宿主通过 frontend/packages/web-app/src/plugins/extension/manager.ts 的 PluginManager 管理插件生命周期。与 CLI 构建端对应的关键逻辑:
- 使用
createInstance创建 Module Federation 运行时实例,并把vue、pinia配置为共享单例(singleton)依赖,与 CLI 构建端shared: ['vue', 'vue-router']呼应; loadPlugin中通过this.mf.registerRemotes([{ name, entry }])注册远程,再调用this.mf.loadRemote(${name}/index)获取插件默认导出——这正好对应 CLI 构建端固定的exposes: { './index': './src/index.ts' }与remoteName;- 插件实例拥有
unloaded / loading / loaded / failed状态机,加载有超时(默认 30 秒)与并发上限(默认 3)保护; activatePlugin会创建插件上下文(IPluginContext),执行module.activate(context),随后把contributes.settingsTabs注册到客户端的设置页签中。
因此,插件能否被正确加载,取决于 CLI 构建端与宿主端对"模块名 + index 入口 + 共享依赖"三者的约定一致——这就是 rpa.config.ts 中 name 字段在整条链路里的重要性所在。
六、参与开发 @rpa/cli 本身
如果你要改进 CLI 包本身(例如调整命令、扩展模板或修改 Module Federation 配置),在 frontend/packages/cli 目录下执行:
# 安装依赖
pnpm install
# 构建 CLI(tsdown 打包)
pnpm build
# 运行类型检查
pnpm typecheck
# 开发监听模式(tsdown --watch)
pnpm dev
各脚本定义在 package.json:
"scripts": {
"build": "tsdown",
"typecheck": "tsc --noEmit",
"dev": "tsdown --watch"
}
构建配置见 tsdown.config.ts:入口为 src/index.ts,输出 ESM 格式,并开启 dts sourcemap(类型声明文件)。src/index.ts 对外只导出两个公共 API:runCli(命令入口)与 defineConfig/RpaConfig(配置类型)。
七、常见问题与排错提示
rpa create提示target directory already exists:目标目录已存在时命令拒绝覆盖,请换一个目录或先移走旧目录。rpa create提示builtin plugin template not found:说明templates/template-vue未随包发布或路径损坏。@rpa/cli的files字段包含bin、dist、templates(见 package.json),确保从发布包安装时这三个目录完整。- 调试日志不显示:检查是否使用了
--debug且命名空间拼写正确;未带参数时启用全部rpa:*。 - 构建后宿主加载失败:优先核对三点——
rpa.config.ts中name与宿主端注册的插件名一致;src/index.ts存在且默认导出definePlugin(...)的模块;publicPath遵循rpa://extensions/<name>/约定(构建端已自动设置,通常无需手动改)。 - 依赖版本不匹配:模板中
workspace:*的@rpa/shared引用只在 pnpm monorepo 内有效,独立发布插件时请改为具体版本号。
结语
@rpa/cli 用三个命令串起了 Astron RPA 插件开发的完整闭环:rpa create 提供标准模板与交互引导,rpa dev 提供 Vite + Module Federation 的开发调试体验,rpa build 产出遵循 rpa://extensions/ 协议的发布产物,最终由宿主端 PluginManager 以模块联邦方式动态加载。理解这条链路,你就能快速为 Astron RPA 编写可分发、可热更的扩展插件;而这一切的起点,就是一条 rpa create 命令。