在前端工程化中，环境变量（Env）是连接“静态代码”与“动态运行环境”的桥梁。很多开发者在使用 Vite 时，往往只停留在“知道怎么写”的阶段，对背后的运行机制、安全红线以及生产环境的动态部署一知半解。

今天，我们就结合企业级项目的真实场景，一次性把 Vite 的环境变量彻底讲透。

一、 核心概念：Vite 内置的dotenv机制

在 Webpack 时代，我们需要手动安装dotenv库来解析.env文件。但在 Vite 中，这一切都被内置了。Vite 在底层自动集成了dotenv和dotenv-expand，能够自动读取项目根目录下的环境配置文件。

核心安全红线：
为了防止数据库密码、私钥等敏感信息意外暴露到浏览器端，Vite 规定：只有以VITE_为前缀的环境变量，才会被暴露给客户端代码（即你在 Vue/React 组件里写的代码）。

# .env VITE_API_BASE_URL=https://api.example.com # ✅ 会暴露给前端 DB_PASSWORD=secret123 # ❌ 不会暴露，前端读取为 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_TIMEOUT=15000

2. 开发环境（.env.development）

# 是否开启 Mock 数据 VITE_ENABLE_MOCK=true # 是否打印调试日志 VITE_ENABLE_DEBUG=true # 覆盖基础配置中的 API 前缀（直连测试服务器） VITE_API_BASE_URL=/dev-api

3. 生产环境（.env.production）

# 关闭 Mock 和调试日志，确保生产环境干净利落 VITE_ENABLE_MOCK=false VITE_ENABLE_DEBUG=false 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 部署，是每一个现代前端工程师的必修课。希望这篇指南能帮你彻底理清思路，写出更优雅、更健壮的工程化代码。