> 本文整理自平台文档 docs/wujies/5.x/platform/architecture/remote-app.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-9196465199da-cover.svg)
后端那一半解决的是「插件 jar 怎么装进来」(见 [插件运行时](/docs/wujies/5.x/platform/architecture/plugin-runtime)); 这一页解决另一半:点了这个菜单,宿主该去加载哪份 JS,以及那份 JS 凭什么能在宿主上下文里跑起来。
如果你要写一个远程应用(建工程、写入口契约、构建产物),看 [前端远程应用工程](/docs/wujies/5.x/platform/plugin/frontend/);这一页讲的是宿主做对了什么 —— 改 wujies-admin/src/plugins/appmarket/**、排查「菜单点开是远程视图不可用」、 或核对某条断言该信哪份文件时读它。
- 应用编码
appCode:app.json的code,同时是产物目录名、落位目录名、入口 URL 里那一段; - 视图键
viewKey:应用views字典的键,形如demo/home; - 入口
entry:产物里那个 ESM 文件的 URL,形如/remote-apps/hello/index.js?v=1.0.0。
一、整条链路
后端 app.json 的 menus[].component = "remote:<appCode>/<视图键>"
│ AppMenuPlanner 幂等 upsert 进 sys_menu.component(只是个字符串)
▼
前端登录后拉菜单树 → permission.ts 的 loadView()
│ 命中 remote: 前缀 → parseRemoteView() 拆出 appCode 与视图键
▼
createRemoteViewComponent(视图键, appCode) ← 只返回一个懒加载函数,此刻还没有 JS
│ 路由真正渲染该视图时:本地视图索引里没有 → 问入口解析器要 entry
▼
GET /app/runtime/remote-apps ← 本租户已启用应用的入口清单
│ entry = /remote-apps/<appCode>/<文件名>?v=<版本号>
▼
loadRemoteApp(entry):import(entry) → 调用安装函数(runtime) → 拿到 { manifest, views }
│ 索引视图键 → 注册路由 → 注入样式
▼
渲染出真正的页面
每一段落在哪个文件:
| 环节 | 实现 |
|---|---|
菜单声明 component | plugins/wujies-<app>-plugin/app.json 的 menus[](范例见 plugins/wujies-hello-plugin/app.json) |
| 前缀常量(前端) | wujies-admin/src/plugins/appmarket/constants.ts 的 REMOTE_VIEW_PREFIX = 'remote:' |
| 前缀常量(后端) | wujies-platform/wujies-modules/wujies-market-core/.../constant/AppMarketConstants.java 的 REMOTE_VIEW_PREFIX = "remote:"(判据内核,平台与中心上架服务共用) |
| 视图键解析 | wujies-admin/src/plugins/appmarket/loader.ts 的 parseRemoteView() |
| 挂到路由 | wujies-admin/src/store/modules/permission.ts 的 filterAsyncRouter() → loadView() |
| 入口清单 API | .../controller/AppRuntimeController.java 的 GET /app/runtime/remote-apps |
| 产物落位 | .../service/AppPackageDeployService.java |
| 装载与注册 | wujies-admin/src/plugins/appmarket/loader.ts、runtime.ts、bootstrap.ts |
二、视图键:remote:<appCode>/<视图键>
解析规则很直白(loader.ts 的 parseRemoteView()):去掉 remote: 前缀后, 第一段(到第一个 / 为止)是 appCode,剩下全部是视图键 —— 视图键自己可以带 /。
菜单里的 component | 解析结果 |
|---|---|
remote:hello/demo/home | appCode hello,视图键 demo/home |
remote:exam/exam/settings | appCode exam,视图键 exam/settings |
remote:hello | 非法:没有 / → 打一条 WARN,loadView() 返回 undefined |
remote:/home | 非法:appCode 为空 |
remote:hello/ | 非法:视图键为空 |
视图键必须与该应用 src/index.ts 里 views 对象的键逐字符一致 (plugins/wujies-hello-plugin/app.json 的 remote:hello/demo/home 对 plugins/wujies-hello-plugin/frontend/src/index.ts 的 views['demo/home'] 就是一组对照)。
### 两种「点不开」要分清
它们的文案、根因、修法都不同,别混:
| 现象 | 什么时候发生 | 根因 | 修法 |
|---|---|---|---|
控制台 [permission] 菜单「X」的 component 解析不出来,已跳过该路由:remote:… | 构建路由树时(登录/刷新),loadView() 返回 undefined | 视图键格式非法(上表后三行)。permission.ts 会把这条路由整个跳过 —— 侧边栏可能还有菜单,点开是空白 | 改 app.json 的 component |
控制台 远程视图不可用: <视图键>(应用 X 未安装或入口地址未配置) | 渲染该视图时,懒加载函数抛错 | 格式合法,但① 本租户没装/没启用这个应用,或② 产物在但里面没有这个视图键 | 先看 GET /app/runtime/remote-apps 有没有它,再让该应用升级一次(升级顺带跑菜单同步) |
菜单由清单声明,所以 app.json 里多写一条不存在的视图键,装到任何一台机器上都会生成这条坏菜单; 它只在点开时暴露,构建期一路绿灯。node scripts/audit-menus.mjs <导出文件> 就是为此存在的体检工具(见第九节)。
三、产物落位:/remote-apps/<appCode>/
宿主的 /remote-apps/ 是磁盘上的一个目录**,不是某个接口。落位由 AppPackageDeployService 在部署/安装/升级时完成:
| 包内 | 落位后 |
|---|---|
assets.backend 那个 jar | <pluginDir> 根下(loader.path 不递归子目录) |
assets.frontend 的目录前缀整棵(通常是 frontend/) | <frontendDir>/<appCode>/,去掉前缀 |
migrations/*.sql | <pluginDir>/migrations/<appCode>/(落位前先清空该目录) |
所以包内是 frontend/index.js,落位后就是 <frontendDir>/<appCode>/index.js —— 前缀被剥掉,文件名保留。这正是入口只取文件名的原因(下一节)。
| 项 | 值 | 在哪 |
|---|---|---|
| 配置键 | app-market.deploy.frontend-dir | wujies-platform/wujies-admin/src/main/resources/application.yml |
| yml 值 | ${WUJIES_FRONTEND_DIR:../wujies-admin/app-market-dist/remote-apps} | application.yml:238(相对路径按后端工作目录解析) |
| 注解兜底值 | 与 yml 默认值同一个字符串 | AppPackageDeployService:131、PluginAppInstaller:74(旧的 ../plus-ui/... 已于 2026-10-27 改齐) |
| dev server 读的位置 | <宿主前端仓库根>/app-market-dist/(不可配置) | `wu |
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-9196465199da-guide.svg)


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