vue-vben-admin 容器化部署完整指南

vue-vben-admin 容器化部署完整指南

【免费下载链接】vue-vben-adminA modern vue admin panel built with Vue3, Shadcn UI, Vite, TypeScript, and Monorepo. It's fast!项目地址: https://gitcode.com/GitHub_Trending/vu/vue-vben-admin

刚上线的后台，同事一刷新路由就 404，改三遍环境变量还是白屏；把整个仓库塞进容器，2GB 镜像直接被拒收。这套 vue-vben-admin 容器化部署方案，把 Vue3 中后台面板从镜像构建到 Nginx 上线一次讲清，适合准备把项目推上生产的同学。

部署链路全景

vue-vben-admin 是 Vue3 + Vite + TypeScript + Monorepo 的中后台管理面板，仓库里同时养着 web-antd、web-ele、playground 好几个 UI 应用。这决定了容器化方案的形态：不是"整仓打包"，而是"构建时选一个应用，运行时只跑一个 Nginx"。

整条链路是这样走的：源码 → 镜像构建（Node 装依赖、Vite 产出 dist）→ 容器运行（Nginx 只发静态文件）→ 端口 8080 对外服务。多阶段构建的价值全在第二步：Node 环境、依赖树、node_modules 全部留在 builder 阶段，最终镜像里只有 nginx:stable-alpine 加一份 dist，体积通常百来 MB，启动秒级，运维交接没有心理负担。

官方在 部署脚本目录 里已经备齐 Dockerfile、nginx.conf 和一键构建脚本，本地直接跑pnpm build:docker就能把镜像打出来，不用从零自己写。

核心配置精讲

多阶段镜像只改两行

Dockerfile 是标准两阶段结构：builder 用 node:22-slim 装依赖并执行 Vite 构建，production 用 nginx:stable-alpine 拷走构建产物。默认构建的是 playground 演示应用，要上线 web-antd 这类正式应用，直接动两行：

RUN pnpm run build --filter=@vben/web-antd COPY --from=builder /app/apps/web-antd/dist /usr/share/nginx/html

💡 不改也能跑：默认构建的就是 playground。.dockerignore已排除 node_modules、dist、.turbo，加上 pnpm store 挂载缓存，重复构建会快很多，这部分一般不用碰。

Nginx 兜底路由别漏

nginx.conf 里真正决定"能不能用"的是 SPA 兜底那一行。Vue Router 是前端路由，服务端只认文件不认路由，没有 fallback 刷新就 404：

location / { root /usr/share/nginx/html; try_files $uri $uri/ /index.html; }

💡 模板默认带了一组 CORS 响应头。API 同域部署时建议在这里顺手加一条/api的 proxy_pass 转发到后端；跨域的话把*换成具体域名，比裸奔安全。

缓存头三行加上去

Vite 产物带内容 hash，文件名变了缓存自然失效，静态资源可以放开长缓存：

location ~* \.(js|css|png|jpg|svg)$ { expires 30d; add_header Cache-Control "public, max-age=2592000"; }

💡 这一段模板里没带，不加也能正常访问，加上之后二次加载明显更快，属于"改三行就回本"的优化。

⚠️ 实战踩坑实录

刷新页面就 404

症状：根路径打开正常，地址栏敲一个内页路由一刷新就 404。根因：SPA 路由全在前端，Nginx 没有兜底。一行解法：location /里补上try_files $uri $uri/ /index.html;，前面精讲里那三行就是完整答案。

端口冲突起不来

连不上、容器反复重启，九成是端口占了。镜像默认监听 8080，宿主机被别的服务占着时就是这个表现。先netstat -tuln | grep 8080看一眼，换个映射端口直接跑：

docker run -d -p 8010:8080 --name vben-admin vben-admin-local

构建中途 OOM 被杀

症状：Docker build 走到 pnpm install 或 build 步骤直接Killed。根因是 monorepo 全量构建吃内存，别急着改镜像。官方 Dockerfile 已写死NODE_OPTIONS=--max-old-space-size=8192，普通机器够用；真 OOM 就把 Docker Desktop 的内存上限调大。

进阶一句话

想接 CI/CD 或 docker-compose 多环境编排，顺着仓库根目录的 turbo 流水线加一个 docker build 步骤即可，构建细节看 官方文档。

没有额外依赖、没有魔法步骤：一条官方脚本出镜像，一个 Nginx 容器跑生产，改两行换应用、加三行上缓存。更多构建细节以官方文档为准，项目更新建议直接盯仓库 CHANGELOG。

【免费下载链接】vue-vben-adminA modern vue admin panel built with Vue3, Shadcn UI, Vite, TypeScript, and Monorepo. It's fast!项目地址: https://gitcode.com/GitHub_Trending/vu/vue-vben-admin