vue-vben-admin Docker 部署指南从多阶段构建到生产上线的完整路径【免费下载链接】vue-vben-adminA modern vue admin panel built with Vue3, Shadcn UI, Vite, TypeScript, and Monorepo. Its fast!项目地址: https://gitcode.com/GitHub_Trending/vu/vue-vben-admin这篇文章带你把 vue-vben-admin 用 Docker 部署成一个可以直接访问的生产服务用仓库自带的 Dockerfile 完成多阶段构建配置 Nginx 做反向代理与静态资源缓存讲清楚哪些环境变量在构建期生效、哪些只能在运行期用再用 Compose 编排、验证并接入 CI 自动化。适合第一次接触容器化部署的开发者照着做一条容器命令就能让后台面板跑起来。先看结果一条命令把后台跑起来部署完成后你拿到的东西是这样的# 构建生产镜像仓库已内置封装脚本 pnpm build:docker # 启动容器宿主 8010 端口映射到容器 8080 端口 docker run -d -p 8010:8080 --name vben-admin-local vben-admin-local # 浏览器访问 curl -I http://localhost:8010 # 返回 200 即服务正常打开http://localhost:8010看到登录页就算部署成功演示账号admin / 123456走的是内置 mock 数据。下面按为什么→怎么做→怎么确认的顺序拆解这条命令背后每一层在做什么。动手前仓库自带了哪些部署文件vue-vben-admin 是一个 pnpm monorepoapps/下有多个前端应用web-antd、web-ele、web-naive 等。仓库已经把容器化部署的工具链备齐了你不需要从零写scripts/deploy/Dockerfile多阶段构建定义构建目标默认是playground演示应用scripts/deploy/nginx.conf生产环境 Nginx 配置监听 8080 端口scripts/deploy/build-local-docker-image.shpnpm build:docker调用的本地构建脚本自动清理旧容器、旧镜像并写构建日志.dockerignore已存在于仓库根目录排除了node_modules、.git、dist等不需要手动创建先确认环境满足 package.json 里的 engines 约束Node 22.18或 24.12、pnpm 11、Docker 20.10。git clone https://gitcode.com/GitHub_Trending/vu/vue-vben-admin cd vue-vben-admin pnpm install多阶段 Dockerfile 怎么写一个阶段编译一个阶段运行多阶段构建的思路很简单第一阶段像工厂装 Node 工具链、装依赖、跑 Vite 打包第二阶段像门店只留一个 Nginx 和打包出来的静态文件。最终镜像里没有 Node 运行时体积小、攻击面也小。仓库的 Dockerfile 关键结构如下注释为简化说明# 阶段一编译环境负责装依赖和打包 FROM node:22-slim AS builder ENV PNPM_HOME/pnpm PATH$PNPM_HOME:$PATH RUN npm i -g corepack WORKDIR /app COPY . . # --mounttypecache 让 pnpm 存储跨构建复用二次构建会明显变快 RUN pnpm install --frozen-lockfile # 只构建前端应用排除 docs 文档站 RUN pnpm run build --filter\!./docs # 阶段二运行环境只有 nginx 和产物 FROM nginx:stable-alpine COPY --frombuilder /app/playground/dist /usr/share/nginx/html COPY --frombuilder /app/scripts/deploy/nginx.conf /etc/nginx/nginx.conf EXPOSE 8080 CMD [nginx, -g, daemon off;]两个可以按需调整的地方换构建目标想部署web-antd而不是playground把COPY --frombuilder的源路径改成/app/apps/web-antd/dist即可本地快速构建直接跑pnpm build:docker它会清理旧的vben-admin-local容器和镜像、执行docker build成功后打印启动命令完整过程记录在同目录的build-local-docker-image.log里怎么确认生效docker images | grep vben-admin-local能看到新镜像且docker history vben-admin-local里最后一层是 nginx 而不是 node说明构建依赖没有被带进最终镜像。Nginx 配置反向代理、SPA 路由与静态资源缓存nginx.conf 里对新手最关键的三处SPA 路由回退。vue-router 的 history 模式下直接访问/dashboard这种子路径服务器上是找不到对应文件的需要 Nginx 兜底到index.html交给前端路由location / { root /usr/share/nginx/html; # 找不到静态文件就回退到 index.htmlhistory 模式刷新页面才不会 404 try_files $uri $uri/ /index.html; }如果不想配这条规则也可以把 playground/.env.production 里的VITE_ROUTER_HISTORY设为hash用#路由绕开服务器回退——代价是 URL 里多一段#。CORS 预检处理。前端接口若跨域请求后端配置里已对OPTIONS请求直接返回 204 并带上Access-Control-Allow-*头更规范的做法是在 Nginx 里加一层location /api/ { proxy_pass ... }反向代理到后端同源后就没有跨域问题。静态资源缓存策略。带 hash 的 JS/CSS 文件名每次构建都会变可以放心给长缓存index.html则必须不缓存否则用户拿不到新版本入口。在location /之外补一段# 带指纹的静态资源缓存 30 天 location ~* \.(js|css|png|jpg|jpeg|svg|woff2?)$ { expires 30d; add_header Cache-Control public, max-age2592000; } # 入口文件不缓存保证发版后立即生效 location /index.html { add_header Cache-Control no-cache; }怎么确认生效curl -I http://localhost:8010/assets/xxx.js响应头里能看到Expires和Cache-Controlcurl -I http://localhost:8010/则不应带长缓存。环境变量管理哪些打进包里哪些运行时才生效这是最容易踩坑的一节。Vite 的规则是以VITE_开头的变量在构建期被静态替换进 JS 文件docker run -e VITE_GLOB_API_URL...这种运行期注入对它们完全无效。每个应用目录各自维护生产配置例如 apps/web-antd/.env.production 和 playground/.env.production常用的几项变量作用示例VITE_GLOB_API_URL后端接口基地址构建期固化https://api.example.com/apiVITE_COMPRESS产物压缩方式none / brotli / gzipgzipVITE_BASE部署基路径子目录部署时必须与 Nginx 路径一致/VITE_ROUTER_HISTORY路由模式 hash / historyhash所以正确的工作流是改对应应用的.env.production→ 重新构建镜像 → 再启动容器。运行期-e传入的变量只会被 Nginx 这类读运行环境的进程感知而当前 nginx.conf 是构建时拷进镜像的静态文件等于整条链路都是构建期定死的——想换接口地址就重建这是静态站点部署的正常节奏。用 Docker Compose 编排多实例部署单机跑一个容器时docker run就够了要做重启自愈、健康检查、将来扩展多个服务比如加一个真实后端Compose 更合适。在项目根目录新建docker-compose.ymlservices: vben-admin: image: vben-admin-local ports: - 8010:8080 restart: always # 每 30 秒探一次首页连续 3 次失败就标记不健康 healthcheck: test: [CMD, wget, -qO-, http://127.0.0.1:8080/] interval: 30s timeout: 5s retries: 3docker compose up -d docker compose ps # STATUS 列出现 healthy 即容器存活且能响应 docker compose logs -f # 实时查看 Nginx 访问与错误日志怎么确认生效docker compose restart vben-admin或杀掉容器restart: always会让它自动拉起docker compose ps里健康检查状态由starting变为healthy说明探测通过。部署验证与排错四个高频问题先跑一遍最小验证清单docker ps | grep vben-admin-local # 容器状态应为 Up docker logs vben-admin-local --tail 50 # 有无报错 curl -I http://localhost:8010 # 200 且 Content-Type 为 text/html⚠️ 有问题时按下面四个方向排查覆盖 90% 的现场情况刷新子页面 404几乎一定是 history 路由缺少回退。检查 Nginx 是否有try_files $uri $uri/ /index.html;或临时改用 hash 路由验证。页面白屏、资源 404多半是VITE_BASE与实际访问路径不匹配。挂在子路径如http://host/admin/部署时.env.production里要设VITE_BASE/admin/并同步调整 Nginx 的root/location然后重新构建。接口跨域失败同源化是首选——在 Nginx 加location /api/ { proxy_pass http://后端地址; }反向代理确认不了时先curl -X OPTIONS看预检响应是否 204。端口被占用导致容器起不来ss -tuln | grep 8010看宿主机端口占用换宿主机侧映射-p 8020:8080即可容器内 8080 不用动。自动化再进一步推送即构建发布手动docker build只适合验证阶段。仓库里 ​.github/workflows/deploy.yml 已经给出了官方 CI 的写法main分支推送时先改.env.production开启 gzip 与 PWA再执行pnpm build:antd最后把dist同步到远端。照这个模式搭一条镜像流水线只需三步推送触发 →pnpm install docker build产出镜像 → 推送到镜像仓库服务器端docker compose pull docker compose up -d完成滚动更新。把这条流程跑通后日常发版就从登录服务器敲命令变成合并 MR 等几分钟。接下来可以做什么容器能跑起来之后值得继续做的几件事给 Nginx 配 HTTPS 证书并把VITE_GLOB_API_URL换成同域地址用docker history和docker system df审一遍镜像体积在 Compose 里加上真实后端服务与共享网络最后把发版窗口固定下来——比如只允许 main 分支触发流水线。容器化部署的意义不在于装上了而在于每次上线的步骤完全一致、可回滚。【免费下载链接】vue-vben-adminA modern vue admin panel built with Vue3, Shadcn UI, Vite, TypeScript, and Monorepo. Its fast!项目地址: https://gitcode.com/GitHub_Trending/vu/vue-vben-admin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考