企业官网建设流程全解析

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

最折磨人的部署，往往卡在"本地能跑、服务器上跑不起来"之间：依赖版本、Node 大版本、mock 服务、Nginx 配置，任何一处没对齐都会白屏。这篇文章面向会基本 Linux 和 Docker 操作、但没做过前端项目容器化部署的开发者，跟着 vue-vben-admin 仓库自带的部署工具链完成容器化部署，目标是让管理面板跑在 Nginx 上。做完之后，你会得到一个可复现的一键构建、一键启动流程，在任何一台装了 Docker 的机器上都能部署出同样效果。

动手前确认两件事

开始动手之前，先花两分钟核对两样东西：本机工具链版本，以及仓库里哪些文件真正参与部署。这两件没确认清楚，后面每一步都会返工。

环境版本速查

先对一下版本，低于下表要求时，直接去各工具官网（Docker 的 get.docker.com、Node 的 nodejs.org）下载安装包升级即可。

定位与部署相关的文件

clone 仓库（地址https://gitcode.com/GitHub_Trending/vu/vue-vben-admin）后进入根目录即可，真正参与部署链的只有 3 个文件：

• scripts/deploy/Dockerfile：定义镜像怎么构建，是整个容器化流程的入口。
• scripts/deploy/nginx.conf：决定镜像里 Nginx 在生产环境如何提供静态资源和处理预检请求。
• .dockerignore：定义构建时哪些本地文件不要送进构建上下文。

把项目塞进容器

环境和文件都确认好了，现在把整个 monorepo 打包成一张镜像。

多阶段构建到底分了几步

思路是"构建"和"运行"彻底分开：构建阶段用 Node + pnpm 安装依赖、执行 build 产出 dist，运行阶段只保留 Nginx 和 dist 产物。这样最终镜像里不需要 Node 环境和源码，体积更小、攻击面更小。官方 Dockerfile 里还设置了 pnpm 缓存、Node 内存上限等细节，下面精简为核心逻辑（完整版见 scripts/deploy/Dockerfile，仓库只读，任何调整请在本地副本中进行）：

# 构建阶段：只负责装依赖和构建 FROM node:22-slim AS builder WORKDIR /app COPY . . RUN npm i -g corepack RUN pnpm install --frozen-lockfile RUN pnpm run build --filter=!./docs # 运行阶段：只保留 Nginx + dist 产物 FROM nginx:stable-alpine AS production COPY --from=builder /app/playground/dist /usr/share/nginx/html COPY --from=builder /app/scripts/deploy/nginx.conf /etc/nginx/nginx.conf EXPOSE 8080 CMD ["nginx", "-g", "daemon off;"]

第二阶段的COPY --from=builder只从第一阶段拿走 dist 和 Nginx 配置，这就是"多阶段"省空间的本质。构建时.dockerignore会把node_modules和.git挡在构建上下文之外，镜像不会白白带上几百 MB 依赖。

构建镜像并首次启动

下面这条命令以仓库根目录为构建上下文，产出打标签为vben-admin:prod的镜像：

docker build -t vben-admin:prod -f scripts/deploy/Dockerfile . docker images | grep vben-admin

构建日志末尾出现 "Builder Success" 字样、docker images里能看到新镜像，说明构建阶段成功。接下来启动容器，-e传入 API 地址和运行环境：

docker run -d -p 8010:8080 \ -e VITE_GLOB_API_URL=https://api.example.com \ -e NODE_ENV=production \ --name vben-admin vben-admin:prod

⚠️ 注意：Vite 的VITE_变量在构建时就会被打进 bundle，运行时-e只对 Node 类服务生效，改 API 地址要在构建前写进.env.production再重新 build。看到什么算成功：浏览器打开http://localhost:8010出现登录页，部署就算打通了；如果白屏，先docker logs vben-admin看报错。

让它在生产环境跑得快

能跑起来之后，下一步是让它跑得快，以及让不同环境的差异有地方可放。

Nginx 缓存与反向代理关键配置

在本地副本的 Nginx 配置里，有 4 条规则直接决定生产环境的体验，官方 scripts/deploy/nginx.conf 已包含完整版，下面是核心片段：

location / { root /usr/share/nginx/html; try_files $uri $uri/ /index.html; } location ~* \.(js|css|png|jpg|svg|ico)$ { expires 30d; } gzip on;

• root /usr/share/nginx/html;：静态资源根目录，必须和 Dockerfile 里COPY的目标路径一致。
• try_files ... /index.html：SPA 路由兜底，刷新任何不存在的子路由都会回落到 index.html，不 404。
• expires 30d：带 hash 的 js/css 文件名内容永不变，可以放心让浏览器缓存 30 天。
• gzip on：Nginx 压缩文本资源后再下发（记得补gzip_types覆盖 css 和 js），网络传输体积大约缩到三分之一。

缓存和压缩生效后，用户二次访问基本全是命中浏览器缓存，首屏观感就是下面这样：

用 .env 文件隔离多环境差异

不同环境的差异全部收敛到.env文件里。以生产环境为例（变量名对照playground/.env.production的实际字段）：

VITE_GLOB_API_URL=https://api.example.com VITE_NITRO_MOCK=false VITE_COMPRESS=gzip

三个变量分别控制接口地址、是否启动 mock、打包压缩策略（none/gzip/brotli）。新增一个环境只需在本地副本复制一份.env.production改名改变量值，不用动任何代码。

docker-compose 编排多实例

单容器跑通后，用 compose 把它变成可管理的"服务"：

services: vben-admin: image: vben-admin:prod ports: - "8010:8080" environment: - NODE_ENV=production restart: always volumes: - ./logs:/var/log/nginx

volumes把宿主机./logs挂到/var/log/nginx，意义在于容器销毁重建后 Nginx 的访问日志和错误日志不丢。启动命令一行搞定：

docker compose up -d

docker compose ps显示服务 Up、宿主机出现logs目录并开始写入 Nginx 日志，即代表编排生效。

部署后最容易踩的 3 个坑

构建和启动都顺利，不代表生产环境稳了。下面 3 处最容易翻车，提前知道能省掉半天排查时间。

静态资源 404→ 现象：刷新页面后 js/css 在浏览器里 404。原因：nginx.conf 的root和 Dockerfile 里COPY的产物路径对不上。一句话修复：在本地副本里把两处路径对齐后重新 build。

API 请求跨域→ 现象：接口请求全报 CORS 错误。原因：前端与 API 不同源，且 OPTIONS 预检没有处理。一句话修复：在 Nginx 的location /加Access-Control-Allow-Origin等响应头（官方 nginx.conf 已带完整预检逻辑，直接用），或让后端配置 allowed origins。

端口被占用→ 现象：docker run立刻报 "port is already allocated"。原因：宿主机 8010 被别的进程占了。一句话修复：用netstat -tuln | grep 8010找到占用进程，换一个空闲端口映射。

把重复构建交给 CI/CD

手动 build 一次没问题，每次发版都手动敲一遍就很折磨。把流程写进一条 workflow：push 到 main 分支自动触发，云 runner 上安装依赖并执行构建、产出镜像，最后到目标服务器docker run替换旧容器，全程无人值守。官方仓库已经有一条可直接参考的部署流程，触发条件和步骤都写得很标准，拿过来改部署目标即可。

参考文件：.github/workflows/deploy.yml

一张镜像、一份 Nginx 配置、一个 compose 文件，就是 vue-vben-admin 容器化部署的全部资产，这也是它能在一小时内上线生产的全部原因。两个可以继续深入的方向：给容器加健康检查（定期 curl 登录页接口，挂了自动重启）、配置 HTTPS 证书自动续期（比如接 acme.sh 定时签发）。

关键文件路径：部署脚本目录scripts/deploy/、vite 构建配置playground/vite.config.ts、环境变量示例playground/.env.production

【免费下载链接】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