> 本文整理自平台文档 docs/wujies/5.x/frontends/admin/conventions.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-0aef1d913916-cover.svg)
这五条不是「建议」,是硬契约。违反其中任何一条,故障通常都是静默的:构建不报错,运行时才炸,而且报错信息往往指向别处。
1. 产物目录名必须等于 appCode
wujies-<code>-plugin/frontend/ → dist/(或 WUJIES_FRONTEND_DIST/<code>/) → /remote-apps/<code>/
四处必须一致:
1. vite.config.ts 里 defineRemoteApp({ appCode }) 的编码与 app.json 的 code(套件按 appCode 命名产物目录); 2. 打包器 package.ps1 的 -FrontendDist 默认值(独立插件仓库布局默认就是仓库根的 frontend/dist); 3. 后端落位目录 app-market.deploy.frontend-dir/<code>/(默认 ../wujies-admin/app-market-dist/remote-apps/<code>,可用环境变量 WUJIES_FRONTEND_DIR 覆盖);两个默认值都是相对启动 cwd 的路径,不在 wujies-platform/ 下启动就会指到别处(启动日志会打两行 [deploy] plugin-dir / frontend-dir = <绝对路径>); 4. 后端拼出的入口 URL /remote-apps/<code>/index.js。
不一致时的表现:菜单一直在解析,控制台只报
[permission] 菜单「xxx」的 component 解析不出来,已跳过该路由
2. 入口 URL 必须带 ?v=<version>
/remote-apps/exam/index.js?v=1.2.0
版本号来自 app.json 的 version。没有它,升级后浏览器缓存会让用户继续跑旧代码。
3. AutoImport 清单必须与宿主逐项一致
远程产物是独立构建的:它继承宿主的运行时,但不继承宿主的构建配置。宿主开了 unplugin-auto-import(vite/plugins/auto-import.ts:vue / vue-router / @vueuse/core / pinia + Element Plus resolver),所以宿主源码里的 ref(...)、useStorage(...) 没有 import 语句。
构建套件 @wujies/ui-plugin-bundler-kit 替插件工程把这份清单钉死为:vue / vue-router / pinia + element-plus 的 ElMessage / ElMessageBox / ElNotification / ElLoading 四个具名。清单没覆盖的名字必须自己显式 import —— 最典型的是 @vueuse/core,宿主有、套件没有:wujies-exam-plugin/frontend/src/components/common/KTableSiderLayout/index.vue 就老老实实写了 import { breakpointsTailwind, useBreakpoints } from '@vueuse/core'。
2026-10-24 起产物只含插件工程自己的 src/(套件不再给宿主路径加别名),所以这一类问题只剩一个来源:手工拷进 src/ 的宿主文件。拷的时候要么补显式 import,要么保证套件的清单覆盖到它。
漏了的表现:
- 构建期不报错(Rollup 当它是全局变量);
- 一装载就
ReferenceError: useStorage is not defined,整个应用变成「远程视图不可用」。
用 npm run tools:check 里的 AutoImport 项守门;单独复查已发布的历史包:
node scripts/check-remote-globals.mjs --dir=<解包后的 frontend 目录>
4. 垫片文件名是硬契约
app-market-dist/app-runtime/ 里的:
dromara-request.js
dromara-components.js
dromara-modal.js
名字来自第三方 npm 作用域 @dromara/*,不是本项目品牌名。同目录还放着 vue.js / vue-router.js / pinia.js / element-plus.js / wujies-components.js / wujies-ui-shared.js,index.html 的 import map 把这九个说明符一并指到 /app-runtime/ 下。下面三处必须一致:
index.html的 import map;scripts/gen-runtime-shims.mjs(生成方);scripts/check-runtime-shims.mjs(校验方)。
> 项目改名时曾用 PowerShell -replace(默认大小写不敏感)把 dromara-request.js 误改成 Wujies-request.js,导致远程应用全部加载失败。
5. 不要写「薄垫片」绕 SDK
已知踩过:某个应用自己复刻了一份 src/utils/request.ts,里面 import { getToken } from '@/utils/auth' —— 这会把宿主源码拉进产物,随后就是缺依赖、双实例、版本漂移。
正确做法:
@/utils/request直接指向@dromara/request;- alias 用正则精确匹配,不要用字符串前缀匹配(否则
@/utils/requestCache也会被吃掉)。
改完跑什么
npm run tools:check # 生成垫片 + 垫片对账 + 产物组件解析 + AutoImport 清单
npm run test:market # loader / bootstrap 单测
两条全绿再提交,比在浏览器里逐个应用点一遍可靠。
常见静默故障
| 你看到的 | 实际原因 |
|---|---|
| 菜单消失,但没有报错 | component 解析不到,路由被跳过 |
| 升级成功但页面没变 | 入口 URL 没带 ?v=,命中旧缓存 |
页面白屏,控制台 ref is not defined | AutoImport preset 少了 |
does not provide an export named 'globalHeaders' | @dromara/request 垫片少了具名导出 |
| 两套 Element Plus 样式打架 | 远程产物把 element-plus 打进了 bundle |
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-0aef1d913916-guide.svg)


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