中国 帮助

前端远程应用(宿主侧)

后端那一半解决的是「插件 jar 怎么装进来」(见 [插件运行时](/docs/wujies/5.x/platform/architecture/pluginruntime)); 这一页解决另一半:点了这个菜单,宿主该去加载哪份 JS,以及

前端远程应用(宿主侧)
封面

> 本文整理自平台文档 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 }
    │  索引视图键 → 注册路由 → 注入样式
    ▼
渲染出真正的页面

每一段落在哪个文件:

环节实现
菜单声明 componentplugins/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/homeappCode hello,视图键 demo/home
remote:exam/exam/settingsappCode 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-dirwujies-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)

章节导览
THE END

喜欢就支持以下吧

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

回到内容