Vue-Pure-Admin 多环境部署完整指南：一套配置跑通本地到上线

Vue-Pure-Admin 多环境部署完整指南：一套配置跑通本地到上线

【免费下载链接】vue-pure-admin全面ESM+Vue3+Vite+Element-Plus+TypeScript编写的一款后台管理系统（兼容移动端）项目地址: https://gitcode.com/GitHub_Trending/vu/vue-pure-admin

vue-pure-admin 是基于 Vue3 + Vite + TypeScript + Element-Plus 的开源后台管理系统模板，完全按 ESM 规范编写。这篇文章围绕「Vue-Pure-Admin 环境配置」讲一件实际的事：同一份代码，如何从本地开发、预发布一直平滑走到生产上线——包括.env文件怎么分工、构建脚本怎么切换模式、压缩与 CDN 开关怎么配、最后如何一键交给 Docker 发布。

先看清楚：这套环境体系能帮你管什么

在动手之前，先花 30 秒了解它覆盖了哪些面。所有行为都由根目录的四个环境文件和package.json里的脚本共同驱动：

一句话概括：开发管"跑得快"，生产管"包得小、发得出"，两者互不干扰。

图：系统登录页实际效果，来自项目src/assets/login资源目录

场景一：四个环境文件的分工与类型转换

🧩 根目录下四个文件各司其职，加载规则遵循 Vite 的约定：.env.local（个人覆盖）>.env.[mode]>.env（公共兜底），因此团队协作时个人差异可以放进不入库的本地文件里。

以生产环境文件为例，核心内容只有几行：

VITE_PUBLIC_PATH = / VITE_ROUTER_HISTORY = "hash" VITE_CDN = false VITE_COMPRESSION = "none"

这些值读进来后不会以字符串原样使用。build/utils.ts 里的wrapperEnv会做一次集中转换：

let realName = envConf[envName].replace(/\\n/g, "\n"); realName = realName === "true" ? true : realName === "false" ? false : realName; if (envName === "VITE_PORT") realName = Number(realName);

带来两个实际好处：

• 在 vite.config.ts 中直接解构出boolean/number，不需要再手动转换；
• 每个变量都有兜底默认值（如端口 8848、压缩 none、CDN false），删错环境变量也不会让构建直接崩掉。

场景二：四条命令切换开发、构建、预发布与产物分析

🚀 环境切换不需要改代码，靠--mode参数选对文件即可。package.json 里已经备好了四条脚本：

两点值得注意：

1. 模式参数必须挂在vite build后面写成--mode staging，写成vite build staging是无效命令，会默默按生产构建。
2. 内存上限已经写死在脚本里，开发 4GB、生产 8GB，大项目 OOM 的概率被大幅压低，这也是官方脚本里NODE_OPTIONS=--max-old-space-size的用意。

构建产物在 vite.config.ts 中按类型分了目录，便于 CDN 配置缓存策略：

chunkFileNames: "static/js/[name]-[hash].js", entryFileNames: "static/js/[name]-[hash].js", assetFileNames: "static/[ext]/[name]-[hash].[ext]"

图：项目内真实图片资源示例，与static/[ext]分类输出规则配合，可按类型命中缓存

场景三：上线前的三个"减重"开关

📦 生产构建时，build/plugins.ts 会根据环境变量决定挂载哪些优化插件：

建议的节奏：日常pnpm build保稳；上预发布用build:staging验证 CDN 链路；体积吃紧时在.env.production打开brotli或both，并给服务器开启对应解压缩。

图：pnpm report产出的分析数据可用于定位体积大户，持续减重

场景四：Docker 一键发布，跳过本地环境差异

🐳 仓库自带 Dockerfile，采用"构建 + 运行"两段式：

FROM node:20-alpine as build-stage RUN pnpm install --frozen-lockfile COPY . . RUN pnpm build FROM nginx:stable-alpine as production-stage COPY --from=build-stage /app/dist /usr/share/nginx/html EXPOSE 80

流程很直白：第一段装依赖并执行pnpm build（锁定 lockfile 保证可复现），第二段只把dist拷进 nginx 对外服务。发布时一条docker build+docker run -p 80:80即可，不再依赖本机 Node 版本——本机要求 Node 22+（见package.json的engines），而构建被容器隔离，环境差异基本消失。

高频坑与直接可用的解法

⚠️ 按踩中频率排序的三个坑：

另外提醒：VITE_HIDE_HOME这类公共项按官方注释只放在.env里配置，避免在多个模式文件中重复定义造成歧义。

小结

Vue-Pure-Admin 的多环境部署核心就是一条链：四个.env文件定行为 →--mode选文件 → 构建脚本管内存 → 压缩/CDN/console 三开关瘦身 → Docker 消除环境差异。把这套配置吃透后，从本地起服务到预发布、正式上线都可以用同一套流程复现。

想动手实践的话，直接把项目拉下来跑一遍：

git clone https://gitcode.com/GitHub_Trending/vu/vue-pure-admin

【免费下载链接】vue-pure-admin全面ESM+Vue3+Vite+Element-Plus+TypeScript编写的一款后台管理系统（兼容移动端）项目地址: https://gitcode.com/GitHub_Trending/vu/vue-pure-admin