中国 帮助

产物与约定

这五条不是「建议」,是硬契约。违反其中任何一条,故障通常都是静默的:构建不报错,运行时才炸,而且报错信息往往指向别处。 1. 产物目录名必须等于 appCode text wujies<codeplugin/frontend/ →

产物与约定
封面

> 本文整理自平台文档 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 definedAutoImport 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)

章节导览
THE END

喜欢就支持以下吧

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

回到内容