> 本文整理自平台文档 docs/wujies/5.x/deploy/frontend.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-1abe3bd0b379-cover.svg)
宿主页是一组静态文件,同一个 nginx 还要兼职反代后端、提供运行期落位的远程应用产物、反代对象存储。要构建前端、或者「应用装成功、点进去 404 / 白屏」,从这页进。远程应用为什么必须是独立 ESM 产物、宿主运行期怎么加载它,见 [远程应用机制](/docs/wujies/5.x/platform/architecture/remote-app);插件前端工程怎么构建,见 [插件前端](/docs/wujies/5.x/platform/plugin/frontend)。
先把名字对齐
wujies-admin 在三处含义不同,凡是路径都要先看清是哪一个:
| 写法 | 是什么 | 判据 |
|---|---|---|
wujies/wujies-admin/ | 宿主前端仓库(Vue 3 / Vite,package.json 的 name 就是它) | 有 vite.config.ts / src/;旧文档里的 plus-ui/ 指同一处 |
wujies-platform/wujies-admin/ | 后端启动模块(Java) | 有 pom.xml / src/main;产物是 wujies-admin.jar |
工作区根 ruoyi/wujies-admin/ | 化石目录,里面只有 app-market-dist/ | 没有 package.json、没有 src/ |
wujies-<code>-plugin/frontend/ | 远程应用前端工程(一个仓库一个应用) | 构建配置只有 @wujies/ui-plugin-bundler-kit 的 defineRemoteApp({ appCode, root }) |
浏览器真正取到 JS 的位置只有一个:宿主前端仓库根下的 app-market-dist/remote-apps/(vite/plugins/appMarketStatic.ts 里 sourceDir = path.resolve(root, 'app-market-dist'))。后端落位写文件的位置是 app-market.deploy.frontend-dir,yml 里是相对路径 ../wujies-admin/app-market-dist/remote-apps,基准是进程工作目录(不是仓库根)。工作目录是 wujies/wujies-platform/ 时两边合一;错成上一层 wujies/ 时落到上面那个化石目录,于是「后端报告落位成功」而「页面打不开」。逐目录对照见 [仓库与目录结构](/docs/wujies/5.x/introduction/structure)。
一、构建:先选模式
| 模式 | 命令(在 wujies-admin 下) | base | API 前缀 | 预压缩 | 用途 |
|---|---|---|---|---|---|
| 生产 | npm run build:prod | /admin/ | .env.production 的 VITE_APP_BASE_API(某套线上环境的绝对地址) | gzip | 挂在 /admin/ 子路径、接口另有一个域名的传统部署 |
| 开发构建 | npm run build:dev | / | /dev-api | 无 | 本地联调产物,接口走 dev server 代理 |
| Docker / 1Panel | vite build --mode docker(package.json 里没有对应 script) | / | /prod-api(相对路径) | none | 容器部署:一个镜像跑在任何域名下 |
mode 决定加载哪个 .env.*,vite.config.ts 里 base: env.VITE_APP_CONTEXT_PATH。dev server 监听 VITE_APP_PORT(三个 .env 里都是 80),/dev-api 的代理目标是 http://127.0.0.1:8086(application.yml 的 server.port 默认值)。build-1panel.ps1 走第三种:node node_modules/vite/bin/vite.js build --mode docker。
Docker 模式相对生产模式只差两点:VITE_APP_BASE_API 用相对路径交给 nginx 反代、VITE_APP_CONTEXT_PATH 用 /(容器自己就是站点根)。.env.production 里的接口地址指向某套线上环境,绝不能进镜像,这正是单独留一份 .env.docker 的原因。
三个 .env 都把 VITE_APP_MARKET_EDITION 注释掉了:版本形态运行期问后端 GET /app/edition,在这里写死就变成第二个真相,后端切成官方版而前端还按用户版跑;只有离线构建或后端取不到时兜底才有意义。
产物目录没有配 build.outDir,就是 Vite 默认的 wujies-admin/dist。appMarketStatic.ts 在 writeBundle 阶段把整棵 app-market-dist/(app-runtime/ 垫片 + remote-apps/ 各应用)复制进 dist/,所以 dist/remote-apps/ 是构建那一刻的快照;build-1panel.ps1 又把整棵 dist/ 拷进前端镜像的上下文,镜像里因此也烘了一份 remote-apps/(这个事实下面坑 3 要用)。运行时垫片不再是打包前置脚本:同一个插件在 configResolved 阶段自己调 scripts/gen-runtime-shims.mjs,单跑 vite build 也是完整的。
远程应用工程自己的产物目录由构建套件的 resolveOutDir 决定:设了 WUJIES_FRONTEND_DIST 就落到 <该变量>/<appCode>/,没设就落到该工程自己的 dist/。目录名必须等于 appCode,这是四处共同的约定(插件 vite 配置、各仓库 package.ps1 的 -FrontendDist、后端落位目录、GET /app/runtime/remote-apps 拼的 URL)。本地联调时让构建即落位:
# 在 wujies\plugins\wujies-<code>-plugin\frontend 下;kit 会自动追加 <appCode> 子目录
$env:WUJIES_FRONTEND_DIST = '<宿主前端仓库根>\app-market-dist\remote-apps'
npm run build
二、四处路径要对齐
入口 URL 形如 /remote-apps/<appCode>/index.js?v=<版本号>,由 AppRuntimeController 拼出。写的一端与读的一端:
| 环境 | 后端写到 | nginx / dev server 从哪读 | 结论 |
|---|---|---|---|
直跑,工作目录 wujies/wujies-platform/ | ../wujies-admin/app-market-dist/remote-apps/<appCode>/ | dev server 读 <前端仓库>/app-market-dist/remote-apps/<appCode>/ | 同一目录 |
直跑,工作目录错成 wujies/ | 同一字符串,解析到化石目录 | 同上 | 两个目录,落位成功但打不开 |
| 容器 | /app/remote-apps/<appCode>/ | /var/www/remote-apps/<appCode>/ | 同一个宿主卷 ./data/remote-apps |
Java 注解里的兜底值与 yml 默认值现在是同一个字符串(2026-10-27 把旧的 ../plus-ui/... 改齐),所以 yml 有没有生效落位目录都是它,唯一还会出错的是工作目录。覆盖口子从高到低:
1. 启动参数 -Dapp-market.deploy.frontend-dir=…(系统属性优先级最高); 2. 环境变量 WUJIES_FRONTEND_DIR,或 Spring 宽松绑定的 APP_MARKET_DEPLOY_FRONTEND_DIR,推荐给绝对路径,彻底和 cwd 解耦; 3. jar 内 yml:改源码目录里的 yml 必须重建 wujies-admin.jar 才生效。
启动日志核对这三行(含义与「存在:false」的告警见 [后端部署](/docs/wujies/5.x/deploy/backend)):
[deploy] plugin-dir = <绝对路径>(存在:true)
[deploy] frontend-dir = <绝对路径>(存在:true)
[deploy] 启动工作目录 user.dir = <目录>(两个相对路径都以它为基准)
容器靠 compose 的两行挂载把两边接到同一个宿主目录,后端读写、nginx 只读:


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