> 本文整理自平台文档 docs/wujies/5.x/platform/plugin/frontend.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-670b9f19e4c9-cover.svg)
这一页解决一件事:把插件的 Vue 页面做成一份能被宿主在运行期装载的 ESM 产物。
它不再属于宿主仓库,而是插件自带的前端工程。读完你应该能:建出一个 frontend/、 写出正确的入口契约、用 @wujies/ui-plugin-bundler-kit 构建、把产物落到宿主认的目录、并用守门脚本自查。
一、三个位置,别混
| # | 是什么 | 在哪 |
|---|---|---|
| 1 | 前端工程(源码,要构建) | 各插件仓库 wujies-<code>-plugin/frontend/,依赖来自已发布的 @wujies/* |
| 2 | 构建产物(index.js + CSS) | 默认各工程 frontend/dist/;本地开发时宿主直接读这里 |
| 3 | 产物落位目录(仅生产 / 没有插件源码的宿主) | 宿主仓库 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-enterprise-plugin/ 一个应用一个仓库:后端 Maven 模块在仓库根
├── pom.xml app.json src/ migrations/
└── frontend/ 该应用的远程应用工程
├── package.json 依赖只有已发布的 @wujies/*
├── vite.config.ts 三行 defineRemoteApp({ appCode, root })
└── src/
├── index.ts 入口契约
├── runtime.ts 宿主运行时持有者
├── api/ 接口层(随包走)
└── views/ 页面
拆仓之前(至 2026-10-24),各应用的前端工程集中在单体仓库 wujies/wujies-plugins/frontend/ 下 (一个应用一份 frontend/<code>-app/)。那 10 个存量应用的旧副本、共享工厂 frontend/build/vite.ts 和 frontend/packages/ 都已删除(旧构建方式靠「宿主源码 alias」,能力已经进了 @wujies/ui-plugin-bundler-kit)。 那棵单体仓库已下线、不作为入口 —— 开发任何应用请进它自己的仓库 wujies-<code>-plugin/frontend/。
二、最短上手
cd C:/Users/you/code/wujies-hello-plugin/frontend
npm install
npm run build # 产物在 frontend/dist/index.js + dist/assets/*.css
# 开发时用 watch:保存源码即增量重建(开发台的「启动前端」等价于此)
npm run dev
产物默认落在工程自己的 dist/,plus-ui 的 dev server 会直接读它。要落位到宿主目录就设 WUJIES_FRONTEND_DIST:
$env:WUJIES_FRONTEND_DIST = 'C:\Users\you\code\plus-ui\app-market-dist\remote-apps'
npm run build # → ...\remote-apps\hello\index.js
hello 自己就是一个独立仓库(cd plugins\wujies-hello-plugin\frontend && npm install && npm run build),依赖与其他插件仓库一样是 npm 上的 @wujies/*@^5.6.6 (@wujies/components 最新 5.6.7,修了预构建产物的 el-* 解析); 新建应用时用 tools/create-plugin/create-plugin.mjs 生成同款前端骨架(四种变体),不用从别的仓库复制。
run dev 就是 vite build --watch(见第七节),不是 Vite dev server,也没有 HMR。 改动保存后等终端出现 built in ...,刷新浏览器即可。
| 环境变量 | 作用 | 不设会怎样 |
|---|---|---|
WUJIES_FRONTEND_DIST | 产物根目录,套件会把 <appCode> 追加在后面 | 产物落在工程自己的 dist/ —— 本地开发正好够用(宿主 dev server 优先读插件仓库的 dist/);只有部署到没有插件源码的宿主或打包时才需要设到 app-market-dist/remote-apps |
WUJIES_FRONTEND_DIR | 覆盖守门脚本(check-remote-apps.mjs / check-runtime-shims.mjs)找插件前端工程的位置 | 默认按同级目录扫描各独立插件仓库 wujies-<code>-plugin/frontend(在宿主前端 plus-ui 的上一级里找 plugins/);指向别的目录可覆盖这个扫描 |
WUJIES_UI_DIR | 拆仓前旧工厂用它定位宿主仓库根(含 package.json / src/main.ts 的那层) | 现在的工程都不需要它 —— @wujies/ui-plugin-bundler-kit 不解析宿主源码;只有把打包器的 -FrontendProject 指回旧工程时才用得上 |
用 @wujies/ui-plugin-bundler-kit 的工程(各独立插件仓库的 frontend/) 只依赖 npm 上的构件,clone 下来 npm install && npm run build 就能出产物。 拆仓前那批旧副本要读宿主的 src/utils、src/enums,缺了宿主直接构建失败 —— 那种工程已在 2026-10-24 删除,不要再照它的写法抄。
三、入口契约
src/index.ts 默认导出一个安装函数,接收宿主运行时,返回 { manifest, views }。 下面的骨架照自真实范例的结构(wujies-hello-plugin/frontend/src/index.ts); 注意 hello 是唯一保留 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:<appC
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-670b9f19e4c9-guide.svg)


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