中国 帮助

前端部署与 nginx

宿主前端选哪种构建模式、远程应用产物落在哪,以及 nginx 里 /prod-api、/remote-apps、SSE 与 WebSocket 该怎么配才不会 404。

前端部署与 nginx
封面

> 本文整理自平台文档 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 下)baseAPI 前缀预压缩用途
生产npm run build:prod/admin/.env.production 的 VITE_APP_BASE_API(某套线上环境的绝对地址)gzip挂在 /admin/ 子路径、接口另有一个域名的传统部署
开发构建npm run build:dev//dev-api无本地联调产物,接口走 dev server 代理
Docker / 1Panelvite 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 只读:

章节导览
THE END

喜欢就支持以下吧

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

回到内容