> 本文整理自平台文档 docs/wujies/1.x/plugin-dev/frontend/index.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-3e44771eb06b-cover.svg)
这一页解决一件事:把插件的 Vue 页面做成一份能被宿主在运行期装载的 ESM 产物。
它不再属于宿主仓库,而是插件自带的前端工程。读完你应该能:建出一个 frontend/<code>-app、 写出正确的入口契约、用共享构建工厂构建、把产物落到宿主认的目录、并用守门脚本自查。
一、三个位置,别混
| # | 是什么 | 在哪 |
|---|---|---|
| 1 | 前端工程(源码,要构建) | 插件仓库 wujies/wujies-plugins/frontend/<code>-app/ |
| 2 | 构建产物(index.js + CSS) | 默认各工程 dist/;本地联调与打包时指到下面第 3 处 |
| 3 | 产物落位目录(宿主 dev server / 生产的静态资源根) | 宿主仓库 plus-ui/app-market-dist/remote-apps/<code>/ |
2026-09-30 起前端工程从宿主仓库的 app-market-poc/ 搬到了插件仓库的 frontend/。 看到 app-market-poc、plus-ui/app-market-app/*、plugins/ruoyi-<name> 这类路径,都是过时的。
工作区是这样的(plus-ui/ 的 package.json 里 name 写的是 wujies-admin,别被名字骗了):
wujies/wujies-plugins/ 插件仓库(三个仓库里唯一放着前端工程的)
├── wujies-hello/ 后端插件:Java + app.json + migrations/
├── frontend/ 远程应用工程,一个 pnpm workspace
│ ├── build/
│ │ ├── vite.ts defineRemoteApp() —— 全部共享构建逻辑
│ │ └── host-source.ts 宿主源码根解析(WUJIES_UI_DIR / 祖先探测)
│ ├── hello-app/
│ │ ├── package.json @wujies-plugins/hello-app
│ │ ├── vite.config.ts 二十来行,只声明本应用真正不同的东西
│ │ ├── app.json 近重复的清单(见第六节警告)
│ │ └── src/
│ │ ├── index.ts 入口契约
│ │ ├── runtime.ts 宿主运行时持有者
│ │ ├── api/ 接口层(随包走)
│ │ └── views/ 页面
│ └── gallery-app/ mall-app/ im-app/ ...
└── package.ps1 打包器(会自己调用这里的 vite 构建)
# wujies/wujies-plugins/pnpm-workspace.yaml
packages:
- 'frontend/*-app'
二、最短上手
cd wujies\wujies-plugins
pnpm install
# 宿主源码根(不是它的 src)。不设也能跑:host-source.ts 会沿祖先目录做结构性探测
$env:WUJIES_UI_DIR = 'C:\Users\TX\Desktop\ruoyi\plus-ui'
# 把产物直接落到宿主 dev server 认的目录,改完刷新浏览器即可
$env:WUJIES_FRONTEND_DIST = 'C:\Users\TX\Desktop\ruoyi\plus-ui\app-market-dist\remote-apps'
pnpm --filter @wujies-plugins/hello-app run build
| 环境变量 | 作用 | 不设会怎样 |
|---|---|---|
WUJIES_UI_DIR | 宿主仓库根(含 package.json / src/main.ts 的那层) | 探测布局;探不到就明确报错,不会让你在半路撞上一堆"找不到模块" |
WUJIES_FRONTEND_DIST | 产物根目录,工厂会把 <appCode> 追加在后面 | 产物落在工程自己的 dist/,本地联调时宿主取不到 |
WUJIES_FRONTEND_DIR | 覆盖 frontend/ 工程根的探测(给守门脚本与打包器用) | 按插件仓库的 <插件仓库>/frontend/ 推导(宿主侧默认从 plus-ui/ 往 ../wujies/wujies-plugins/frontend 找) |
hello-app 的配置里写了 standalone: true —— 它刻意不 import 宿主任何源码,所以没有宿主仓库也能构建。 其余应用都要读宿主的 src/utils、src/enums 等,缺了宿主会直接构建失败。
三、入口契约
src/index.ts 默认导出一个安装函数,接收宿主运行时,返回 { manifest, views }。 下面的骨架照自真实范例的结构(wujies/wujies-plugins/frontend/hello-app/src/index.ts); 注意 hello-app 是唯一保留 manifest.routes 的例外(3 条 /remote-demo/ 路由), 骨架里刻意用 routes: [] 展示挂菜单应用**的常规写法:
const manifest = {
code: 'hello',
name: '示例远程应用',
version: '0.1.0',
// 见下:挂到宿主菜单上的应用,这里必须是空数组
routes: []
};
setRemoteRuntime(runtime);
return {
manifest,
views: {
// 约定:加载器返回 { default: Component }
'demo/home': () => ({ default: DemoHome })
}
};
}
| 字段 | 必填 | 说明 |
|---|---|---|
code | 是 | 应用编码,必须与后端 app.json 的 code 一致 |
name | 是 | 应用名 |
version | 是 | 版本号;仅供参考,宿主以服务端清单为准 |
routes | 是(数组) | 挂菜单的应用请写 [] |
views | 是 | 视图键 → 加载器 |
manifest 只是前端侧的运行时清单,它不被服务端校验(服务端只看后端那份 app.json), 所以前端 manifest.version 与后端 app.json 的版本可以不一致而不报错。
加载器的返回值必须能被解包成 { default: Component };直接返回组件本体也兼容, 但推荐统一写 () => ({ default: X }) —— 与 import() 的语义一致。 宿主侧解析代码在 plus-ui/src/plugins/appmarket/loader.ts。
### 3.1 视图键(view key)约定
后端 app.json 的菜单里,component 写 remote:<appCode>/<视图键>:
{ "key": "hello-probe", "type": "C", "path": "probe", "component": "remote:hello/demo/home" }
hello-app/src/index.ts 就是一组对照)。
remote:hello= 应用编码hello;demo/home= 视图键,必须与views的键逐字符一致(hello-app/app.json与
对不上的后果是悬空菜单:菜单是清单声明的,所以全新安装也会照建, 点开只得到控制台一句「component 解析不出来,已跳过该路由」。hello 历史上就踩过 (清单写 remote:hello/hello/list,而前端从没注册过 hello/list)。
### 3.2 routes 为什么留空
manifest.routes 是另一个东西:它是远程应用自己往宿主 router 上注册的顶级路由。 宿主的 loader.ts 在路由没有 parentName 时就 router.addRoute(route) —— 注册出来的是 没有 Layout 的裸路由。
而菜单管线会为同一个 path 再生成一条**包在 Layo
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-3e44771eb06b-guide.svg)


评论区需要浏览器启用 JavaScript 才能加载。