在前端工程化中环境变量Env是连接“静态代码”与“动态运行环境”的桥梁。很多开发者在使用 Vite 时往往只停留在“知道怎么写”的阶段对背后的运行机制、安全红线以及生产环境的动态部署一知半解。今天我们就结合企业级项目的真实场景一次性把 Vite 的环境变量彻底讲透。一、 核心概念Vite 内置的dotenv机制在 Webpack 时代我们需要手动安装dotenv库来解析.env文件。但在 Vite 中这一切都被内置了。Vite 在底层自动集成了dotenv和dotenv-expand能够自动读取项目根目录下的环境配置文件。核心安全红线为了防止数据库密码、私钥等敏感信息意外暴露到浏览器端Vite 规定只有以VITE_为前缀的环境变量才会被暴露给客户端代码即你在 Vue/React 组件里写的代码。# .env VITE_API_BASE_URLhttps://api.example.com # ✅ 会暴露给前端 DB_PASSWORDsecret123 # ❌ 不会暴露前端读取为 undefined二、 文件加载机制一半固定一半自定义Vite 的环境变量文件必须放在项目的根目录和package.json同级。它的加载机制是“合并与覆盖”。1. 基础与模式文件Vite 默认认识两个固定的模式文件.env所有环境都会加载的公共基础配置。.env.development执行npm run dev时加载。.env.production执行npm run build时加载。2. 自定义模式除了上述两个其他的名字你完全可以自定义比如.env.test或.env.staging。你只需要在package.json中通过--mode参数明确告诉 Vite 即可scripts: { dev: vite, build: vite build, build:test: vite build --mode test // 自定义加载 .env.test }3. 加载优先级当执行构建时Vite 会先加载.env再加载对应模式的文件。如果存在同名变量模式文件的值会覆盖.env的值。此外.env.local文件通常用于本地私有配置优先级最高且建议加入.gitignore。三、 生产环境动态 IP 部署方案这是企业级项目中最常遇到的痛点开发环境对接测试服务器但生产环境部署到客户现场时IP 和端口是动态的无法提前写死。核心认知Vite 的server.proxy仅仅在本地开发环境生效当你执行npm run build后生成的是纯静态文件代理配置自然失效。优雅解决方案相对路径 Nginx 反向代理第一步在.env中配置统一的相对路径前缀# .env.development VITE_API_BASE_URL/dev-api # .env.production VITE_API_BASE_URL/api第二步在 Axios 封装中使用const request axios.create({ baseURL: import.meta.env.VITE_API_BASE_URL, // 读取相对路径 timeout: 10000 })第三步服务器Nginx配置拦截无论你的项目部署在http://192.168.1.100:8080还是https://www.customer.com浏览器发出的请求都会自动拼接为当前域名/api/xxx。此时只需在 Nginx 中配置反向代理将/api转发到现场真实的后端服务 IP 即可location /api { proxy_pass http://现场真实的后端IP:端口; proxy_set_header Host $host; }通过这种架构前端代码真正做到了“一次打包到处运行”。四、 运行环境的本质差异import.meta.envvsloadEnv很多开发者在vite.config.js中尝试使用import.meta.env却报错这是因为没有理解 Vite 的两种运行环境。import.meta.env客户端环境运行在浏览器中。Vite 在打包时会把代码里所有的import.meta.env.VITE_XXX静态替换成具体的字符串。它只能用在src/目录下的业务代码中。loadEnv服务端环境运行在 Node.js 中。vite.config.js是在打包开始前执行的此时 Vite 还没开始干活自然没有生成import.meta.env。因此必须使用loadEnv主动读取。loadEnv参数详解import { defineConfig, loadEnv } from vite export default defineConfig(({ mode }) { // loadEnv(当前模式, 当前工作目录, 变量前缀) const env loadEnv(mode, process.cwd(), ) return { // 将环境变量注入到全局供 vite.config.js 内部使用 define: { __APP_SECRET__: JSON.stringify(env.APP_SECRET) } } })这里必须提到process.cwd()Current Working Directory。它获取的是你执行node命令时所在的目录而不是代码文件所在的目录。在 Vite 中我们约定必须在项目根目录执行npm run dev因此process.cwd()永远指向项目根目录确保能准确找到.env文件。五、 企业级项目的标准配置模板在企业级项目中环境变量不宜过多核心是解决接口通信和应用基础标识。以下是经过实战检验的必备变量模板1. 基础配置.env# 应用标题用于动态修改网页 title VITE_APP_TITLE企业级管理系统 # 接口请求的统一前缀 VITE_API_BASE_URL/api # 接口超时时间毫秒 VITE_API_TIMEOUT150002. 开发环境.env.development# 是否开启 Mock 数据 VITE_ENABLE_MOCKtrue # 是否打印调试日志 VITE_ENABLE_DEBUGtrue # 覆盖基础配置中的 API 前缀直连测试服务器 VITE_API_BASE_URL/dev-api3. 生产环境.env.production# 关闭 Mock 和调试日志确保生产环境干净利落 VITE_ENABLE_MOCKfalse VITE_ENABLE_DEBUGfalse VITE_API_BASE_URL/api六、 进阶最佳实践动态网页标题很多项目习惯在index.html中写死title但这在单页应用SPA中体验极差。最佳实践是结合 Vue Router 动态更新标题。1. 路由配置中定义标题const routes [ { path: /dashboard, component: () import(/views/Dashboard.vue), meta: { title: 控制台 } } ]2. 在main.ts中监听路由变化import router from ./router router.afterEach((to) { const defaultTitle import.meta.env.VITE_APP_TITLE // 动态拼接页面标题 - 默认标题 document.title to.meta.title ? ${to.meta.title} - ${defaultTitle} : defaultTitle })这种方式既保留了环境变量中的默认标题又实现了页面级别的精准标题管理是企业级中后台系统的标配。总结Vite 的环境变量设计兼顾了开发效率与生产安全。掌握.env的加载机制、理解import.meta.env与loadEnv的边界、熟练运用相对路径配合 Nginx 解决动态 IP 部署是每一个现代前端工程师的必修课。希望这篇指南能帮你彻底理清思路写出更优雅、更健壮的工程化代码。