> 本文整理自平台文档 docs/wujies/1.x/deploy/frontend.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-f28c6cfdaa45-cover.svg)
Wujies 无界平台的宿主前端是一个 Vue 3 + Vite 单页应用(仓库 plus-ui),产物是一组静态文件,由 nginx 托管。同一个 nginx 还要做三件额外的事:反代后端接口(/prod-api/)、提供运行期落位的远程应用产物(/remote-apps/)、反代对象存储(/minio/)。
本页解决三件事:
1. 宿主前端用哪种模式构建、产物落在哪个目录; 2. 远程应用产物的物理路径在「本机直跑」与「容器」两种形态下分别是什么,怎么和后端 app-market.deploy.frontend-dir、nginx 对齐 —— 这是这一章最容易出错的一环; 3. deploy/docker/frontend/nginx.conf 逐段在做什么。
远程应用为什么必须是独立 ESM 产物、宿主怎么在运行期加载它,见 [/advanced/remote-app](/docs/wujies/1.x/advanced/remote-app);插件前端工程怎么构建、产物目录名有什么约定,见 [/plugin-dev/frontend/](/docs/wujies/1.x/plugin-dev/frontend/)。
命名先对齐:三个 wujies-admin、两个 app-market-dist
wujies-admin 这个名字在三处含义不同,凡是路径都要先看清是哪一个:
| 写法 | 是什么 | 判据 |
|---|---|---|
plus-ui/ | 宿主前端仓库(Vue 3 / Vite) | 有 vite.config.ts / src/;它的 package.json 里 name 写的是 wujies-admin,这就是混淆来源 |
wujies-platform/wujies-admin/ | 后端启动模块(Java) | 有 pom.xml / src/main;产物是 wujies-admin.jar |
工作区顶层 wujies-admin/ | 只有 app-market-dist/ —— 前端产物的落位目录 | 里面没有 package.json、没有 src/ |
wujies/wujies-plugins/frontend/<code>-app/ | 远程应用前端工程(源码,pnpm workspace) | 构建配置走 frontend/build/vite.ts 的 defineRemoteApp |
- 后端落位写文件的位置是工作区顶层的
wujies-admin/app-market-dist/remote-apps/(application.yml里frontend-dir的当前值); - 浏览器真正取到 JS 的位置是
plus-ui/app-market-dist/remote-apps/(plus-ui/vite/plugins/appMarketStatic.ts的sourceDir = <plus-ui 根>/app-market-dist)。
两者是独立的物理目录(都不是 junction / symlink),所以「后端落位成功」与「页面能打开」可能对不上。逐目录的实测对照见 [/guide/structure](/docs/wujies/1.x/guide/structure)。
三种构建模式
| 模式 | 命令(在 plus-ui 下) | base | API 前缀 | 产物目录 | 用途 |
|---|---|---|---|---|---|
| 生产 | npm run build:prod | .env.production 的 VITE_APP_CONTEXT_PATH = /admin/ | .env.production 的 VITE_APP_BASE_API(指向某套线上环境的绝对地址) | plus-ui/dist | 部署在 /admin/ 子路径下、接口在另一个域名的传统部署 |
| 开发构建 | npm run build:dev | .env.development 的 VITE_APP_CONTEXT_PATH = / | /dev-api | plus-ui/dist | 本地联调产物,接口走 dev server 的代理 |
| Docker / 1Panel | vite build --mode docker(package.json 里没有对应的 npm script) | .env.docker 的 VITE_APP_CONTEXT_PATH = / | /prod-api(相对路径) | plus-ui/dist | 容器部署:一个镜像跑在任何域名下 |
三种模式都靠 mode 决定加载哪个 .env.* 文件,plus-ui/vite.config.ts 里 base: env.VITE_APP_CONTEXT_PATH;dev server 的接口代理目标是 http://127.0.0.1:8086(server.port 的默认值,见 wujies-admin/src/main/resources/application.yml)。build-1panel.ps1 用的是第三种:
# build-1panel.ps1 内部(Push-Location 到 plus-ui 之后)
& node 'scripts/gen-runtime-shims.mjs'
& node 'node_modules/vite/bin/vite.js' build --mode docker
-SkipFrontend 会跳过这两条命令,复用已有 dist/;无论跳不跳,脚本都会检查 dist/index.html 是否存在,不存在直接抛错。
1. VITE_APP_BASE_API 用相对路径 /prod-api,由 nginx 反代到后端容器,不写死任何域名 / IP; 2. VITE_APP_CONTEXT_PATH 用 /,容器自己就是站点根,不再挂 /admin 子路径。 .env.production 里的接口地址指向某套线上环境,绝不能进镜像 —— 这正是要单独有一个 .env.docker 的原因。
### 产物目录就是 Vite 默认的 dist
工程里没有配置 build.outDir(plus-ui/vite.config.ts 里没有这一项),所以宿主前端的产物目录是 Vite 的默认值 plus-ui/dist。
plus-ui/vite/plugins/appMarketStatic.ts 在 writeBundle 阶段会把整棵 plus-ui/app-market-dist/(app-runtime/ 垫片 + remote-apps/ 各应用)复制进 dist/。所以 dist/remote-apps/ 里是构建那一刻的产物快照,随后 build-1panel.ps1 又把整棵 dist/ 拷进前端镜像的构建上下文 —— 镜像里因此也有一份 remote-apps/。这一点在下面的「坑 3」里会用到。
远程应用工程自己的产物目录由共享工厂决定,不是各工程手写 outDir(wujies/wujies-plugins/frontend/build/vite.ts 的 resolveOutDir):
- 设了环境变量
WUJIES_FRONTEND_DIST→ 产物落到<该变量>/<appCode>/; - 没设 → 落到该工程自己的
dist/(自包含,可单独验证)。
目录名必须等于应用编码 appCode,这是四处共同的约定:vite 插件的 appCode、wujies/wujies-plugins/package.ps1 的 -FrontendDist 默认值、后端落位目录、GET /app/runtime/remote-apps 拼出的 URL。细节见 [/plugin-dev/frontend/](/docs/wujies/1.x/plugin-dev/frontend/)。
/remote-apps/ 的物理路径:谁写、谁读
远程应用的入口 URL 形如 /remote-apps/<appCode>/index.js?v=<版本号>,由 AppRuntimeController 拼出。这个前缀在三处约定,两处环境下的物理路径不同:
| 环境 | 后端写到哪 | 谁从哪读 | 对齐情况 |
|---|---|---|---|
本机直跑(后端工作目录 wujies-platform/) | ../wujies-admin/app-market-dist/remote-apps/<appCode>/,即工作区顶层那个 wujies-admin/ | plus-ui dev server 读 plus-ui/app-market-dist/remote-apps/<appCode>/ | 两个目录,直跑时可能「落位成功但页面打不开」 |
| 容器(1Panel / 手工 Docker) | /app/remote-apps/<appCode>/ | nginx 容器读 `/var/www/re |
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-f28c6cfdaa45-guide.svg)


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