3 步配好 Vue-Pure-Admin 多环境部署：从 .env 到可上线构建物
【免费下载链接】vue-pure-admin全面ESM+Vue3+Vite+Element-Plus+TypeScript编写的一款后台管理系统（兼容移动端）项目地址: https://gitcode.com/GitHub_Trending/vu/vue-pure-admin
读完这篇，你会独立完成Vue-Pure-Admin 环境配置：从.env文件到Vite 多环境构建，再到按环境产出可上线的部署物，也就是前端多环境部署的完整闭环。它基于 Vue3 + Vite + TypeScript + Element-Plus，整套配置其实只集中在两处——根目录的几个.env文件，和build/目录下的几个构建脚本。你把这两处读懂，剩下的只是照着命令跑。
一、先搞懂环境是怎么被识别和加载的
一切环境差异，都源于 Vite 的mode（模式）概念。你可以把它理解成「当前这套构建要用哪份变量表」。它有三个入口：
pnpm dev默认mode = development；pnpm build默认mode = production；- 显式写
--mode staging时才用staging。
确定 mode 后，Vite 会按「后加载覆盖先加载」的顺序读取根目录下的变量文件，优先级从高到低是：.env.[mode].local→.env.[mode]→.env.local→.env。这里的关键是：.env是所有模式的兜底基线，.env.[mode]放该模式专属值，而带.local的文件通常写进.gitignore，留给团队成员各自覆盖、不进版本库。
具体到这个项目，四个文件分工很清晰：
# .env（基线，所有模式都生效） VITE_PORT = 8848 # 本地端口 VITE_HIDE_HOME = false # 是否隐藏首页 # .env.development（开发模式） VITE_PUBLIC_PATH = / VITE_ROUTER_HISTORY = "hash" # .env.production（线上模式） VITE_PUBLIC_PATH = / VITE_ROUTER_HISTORY = "hash" VITE_CDN = false # 线上不外部化依赖 VITE_COMPRESSION = "none"注意两点：变量名必须带
VITE_前缀才会被注入到前端代码里；另外mode 不等于NODE_ENV，.env.staging里特意注释掉了NODE_ENV就是提醒你别混用这两者。
二、配置如何写进构建：wrapperEnv 与 vite.config.ts
.env里的值读进来全是字符串，但代码里要拿到数字、布尔。项目没有直接裸用，而是在 build/utils.ts 里放了个wrapperEnv做一层类型收敛，核心就这几步：
const wrapperEnv = (envConf: Recordable): ViteEnv => { const ret: ViteEnv = { VITE_PORT: 8848, // 先给一组兜底默认值 VITE_PUBLIC_PATH: "", VITE_ROUTER_HISTORY: "", VITE_CDN: false, VITE_COMPRESSION: "none" }; for (const envName of Object.keys(envConf)) { let realName = envConf[envName].replace(/\\n/g, "\n"); realName = realName === "true" ? true : realName === "false" ? false : realName; if (envName === "VITE_PORT") realName = Number(realName); // 端口转数字 ret[envName] = realName; } return ret; };这里的设计有两层好处：一是没配的变量有默认值，不会因为漏写而报undefined；二是字符串被自动纠正成true/false/数字，让业务代码能拿到类型正确的配置。
拿到的这套配置，最终在 vite.config.ts 里被消费成 Vite 的真实字段：
const { VITE_CDN, VITE_PORT, VITE_COMPRESSION, VITE_PUBLIC_PATH } = wrapperEnv(loadEnv(mode, root)); return { base: VITE_PUBLIC_PATH, // 部署的公共路径 server: { port: VITE_PORT, // .env 的 8848 落到这 host: "0.0.0.0" }, plugins: await getPluginsList(VITE_CDN, VITE_COMPRESSION), build: { target: "es2015", sourcemap: false, chunkSizeWarningLimit: 4000 } };一句话概括数据流：.env→loadEnv(mode)→wrapperEnv→vite.config.ts。所以你在抓开发服务器请求时，能看到VITE_PORT = 8848最终生效在Host上：
三、如何按环境产出构建物：一条命令对应一套产物
环境最终体现在 package.json 的scripts里，每条命令对应一套产物，你可以按需挑选：
{ "dev": "NODE_OPTIONS=--max-old-space-size=4096 vite", "build": "rimraf dist && NODE_OPTIONS=--max-old-space-size=8192 vite build && generate-version-file", "build:staging": "rimraf dist && vite build --mode staging", "report": "rimraf dist && vite build" }- 开发：
pnpm dev起热重载服务，内存给到 4GB 足够流畅。 - 线上：
pnpm build先rimraf dist清旧产物，再走production模式，NODE_OPTIONS把堆上限抬到 8GB 应对大项目构建。 - 预发布：
pnpm build:staging用--mode staging走.env.staging，产物和线上行为基本一致，适合上线前验证。 - 体积报告：
pnpm report会额外生成一份report.html打包分析页，用来排查哪块 bundle 偏大。
这里的关键是rimraf dist：每次构建前都清空输出目录，避免旧文件混进新版本，保证部署一致性。
四、生产环境的两个开关：CDN 与压缩
真正的「按环境差异化」，靠的是两个布尔/枚举开关，它们在 build/plugins.ts 里被做成按需挂载的插件：
| 能力 | 控制变量 | development | staging | production |
|---|---|---|---|---|
| 依赖外部化（CDN） | VITE_CDN | false（默认） | true | false |
| 静态资源压缩 | VITE_COMPRESSION | none | none | none |
去除console | removeConsole | 构建时生效 | 构建时生效 | 构建时生效 |
| 打包体积分析 | npm_lifecycle_event | 仅report模式开启 | — | — |
- CDN：
VITE_CDN ? cdn : null，只有为true时才会把vue、element-plus等基础库换成外链，换体积为运行时请求。预发布开着它做验证，线上默认关掉，稳妥优先。 - 压缩：
configCompressPlugin(VITE_COMPRESSION)按取值产出gzip/brotli/both，加-clear后缀还会删掉原始文件（如gzip-clear），默认none什么都不做，需要时再打开。 - 去 console：
removeConsole是构建场景恒定挂载的，且用external白名单保住了iconfont.js不被误删——这类「默认开、按例外关」的处理很值得借鉴。
五、踩坑与自查：环境变量不生效、构建内存不足、mode 传参错误
问题多半出在这三类，你可以对照下面逐条排。
环境变量不生效的 3 步自查
- 看前缀：变量名是否以
VITE_开头？没前缀的不会被注入前端。 - 看文件：变量是否写在项目根目录对应的
.env文件里？写在子目录不会生效；本地想覆盖就写.env.[mode].local。 - 重启：
.env变更需要重启 dev server才加载，热更新不会自动重新读环境文件。
构建内存不足怎么调
- 临时救急：
export NODE_OPTIONS=--max-old-space-size=8192，把堆上限先抬上去。 - 长期方案：像本项目一样，直接写进
scripts（dev 给 4GB、build 给 8GB），团队统一、不依赖个人环境。 - 若仍 OOM，先跑
pnpm report看是不是某块依赖过大，从源头优化比一味加内存更有效。
mode 传参错误的正确姿势
- ✅ 正确：
vite build --mode staging - ❌ 错误：
vite build staging（把模式当位置参数，Vite 不认识）
写对模式，.env.staging才会被加载，产物行为才会跟预期一致。
下一步
到这里，从「mode 识别加载」→「类型转换写进构建」→「按环境出产物」→「生产开关」→「排错」这条主线就闭环了。想动手的话，先把仓库拉到本地，改一下.env.development里的VITE_PORT重启验证，再分别跑pnpm build和pnpm build:staging对比dist，你对这套多环境体系的印象会立刻从「概念」变成「手感」。
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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
