在现代前端工程化开发中，环境变量（Environment Variables）是管理不同部署环境（开发、测试、预发、生产）配置的核心机制。Vite 作为新一代构建工具，对环境变量提供了简洁而强大的支持。
本文将深入讲解Vite 环境变量的加载规则、作用域、安全机制、自定义前缀配置、类型支持及最佳实践，助你写出安全、灵活、可维护的项目配置。
一、Vite 环境变量基础
🔑 核心规则
- 只有带有指定前缀的变量才会暴露给客户端源码；
- 在代码中通过
import.meta.env访问； - 环境变量文件需放在项目根目录；
- 支持多环境配置（
.env.development,..env.production` 等）。
⚠️安全设计：未匹配前缀的变量不会被打包到客户端代码中，避免敏感信息泄露。
二、环境变量前缀：默认与自定义
默认前缀：VITE_
Vite 默认只将以VITE_开头的环境变量注入到客户端代码中：
# .envVITE_API_BASE=https://api.example.com# ✅ 会暴露DB_PASSWORD=secret123# ❌ 不会暴露// src/main.jsconsole.log(import.meta.env.VITE_API_BASE);// "https://api.example.com"console.log(import.meta.env.DB_PASSWORD);// undefined自定义前缀：envPrefix配置
你可以通过vite.config.js中的envPrefix选项修改或扩展前缀：
// vite.config.jsimport{defineConfig}from'vite';exportdefaultdefineConfig({envPrefix:'MYAPP_',// 使用单个自定义前缀});或者支持多个前缀：
exportdefaultdefineConfig({envPrefix:['MYAPP_','COMPANY_'],// 数组形式支持多个前缀});配置后，只有以MYAPP_或COMPANY_开头的变量才会被注入：
# .envMYAPP_THEME=darkCOMPANY_LOGO_URL=/logo.pngSECRET_KEY=abc123console.log(import.meta.env.MYAPP_THEME);// "dark"console.log(import.meta.env.COMPANY_LOGO_URL);// "/logo.png"console.log(import.meta.env.SECRET_KEY);// undefined💡使用场景：
- 统一团队命名规范（如沿用
REACT_APP_）；- 多品牌项目共用代码库时隔离配置；
- 避免与 CI/CD 系统中的变量名冲突。
⚠️安全警告：
切勿将envPrefix设为空字符串（envPrefix: ''），这会导致所有环境变量暴露给浏览器，造成严重安全风险。
三、环境变量文件加载优先级
Vite 按以下顺序加载.env文件（后加载的覆盖先加载的）：
.env # 所有环境通用 .env.local # 所有环境通用，但会被 git 忽略（用于本地私有配置） .env.[mode] # 指定模式专用（如 .env.development） .env.[mode].local # 指定模式专用 + 本地私有（最高优先级）模式（mode）说明
- 开发服务器默认使用
development模式； - 构建命令默认使用
production模式； - 可通过
--mode自定义：vite build --mode staging# 加载 .env.staging 和 .env.staging.local
📌 注意：无论使用何种前缀，文件加载逻辑不变，
envPrefix仅控制哪些变量最终注入到import.meta.env。
四、在代码中使用环境变量
客户端代码（src/ 目录下）
// 访问自定义前缀变量constapiUrl=import.meta.env.MYAPP_API_URL;// 使用内置布尔变量（不受 envPrefix 影响）if(import.meta.env.DEV){console.log('Running in development mode');}// 注意：所有值都是字符串！constenableFeature=import.meta.env.MYAPP_FEATURE_FLAG==='true';内置环境变量（始终可用）
以下变量由 Vite 自动注入，无需定义，也不受envPrefix影响：
| 变量 | 类型 | 说明 |
|---|---|---|
import.meta.env.MODE | string | 当前运行模式（如'development'） |
import.meta.env.DEV | boolean | 是否为开发模式 |
import.meta.env.PROD | boolean | 是否为生产模式 |
import.meta.env.BASE_URL | string | 部署基路径（来自base配置） |
五、在 Vite 配置文件中使用环境变量
vite.config.js运行在 Node.js 环境，可访问所有.env文件中的变量（包括无前缀的）：
// vite.config.jsexportdefaultdefineConfig({envPrefix:'MYAPP_',server:{proxy:{'/api':{// 安全使用内部变量（不会暴露给前端）target:process.env.INTERNAL_API_HOST||'http://localhost:8080',changeOrigin:true}}}});✅最佳实践：
敏感配置（如代理目标、内部密钥）应使用无前缀变量，并通过process.env在构建配置中使用。
六、TypeScript 类型安全支持
为获得完整的类型提示和编译检查，需扩展ImportMetaEnv接口：
// src/env.d.ts/// <reference types="vite/client" />interfaceImportMetaEnv{readonlyMYAPP_API_URL:string;readonlyMYAPP_ENABLE_ANALYTICS:string;readonlyMYAPP_VERSION:string;// 添加你实际使用的变量}interfaceImportMeta{readonlyenv:ImportMetaEnv;}之后在 TypeScript 文件中即可享受自动补全和类型校验：
// ✅ 类型安全consturl=import.meta.env.MYAPP_API_URL;// string// ❌ 编译错误（如果未声明）// import.meta.env.UNKNOWN_VAR;七、最佳实践清单
✅推荐做法：
- 显式配置
envPrefix提高项目可读性和一致性； - 将
.env.local加入.gitignore，用于本地调试配置； - 敏感信息（密码、密钥）绝不使用暴露前缀；
- 布尔值统一用
'true'/'false'字符串表示，并封装解析函数； - 利用
DEV/PROD内置变量做环境判断，而非自定义变量。
❌避免：
- 在客户端代码中使用
process.env（浏览器不支持）； - 修改
.env后不重启开发服务器（Vite 仅启动时加载）； - 将 API 密钥、数据库凭证等放入暴露前缀变量；
- 使用空字符串作为
envPrefix。
八、常见误区澄清
❌ 误区：所有.env变量都会进入前端代码
事实：只有匹配
envPrefix的变量才会注入，其余仅在构建时可用。
❌ 误区：envPrefix改变后，旧变量名仍有效
事实：必须同步更新
.env文件中的变量名，否则将变为undefined。
❌ 误区：可以在运行时动态切换环境变量
事实：环境变量在构建时静态注入，无法在浏览器中动态修改。
九、总结
Vite 的环境变量机制通过前缀过滤 + 静态注入实现了安全与灵活性的平衡：
- 客户端安全边界：由
envPrefix明确划定； - 构建灵活性：
vite.config.js可访问全部环境变量； - 开发体验：内置
DEV/PROD、TS 类型支持、多环境文件； - 工程规范：鼓励配置外置、敏感信息隔离。
合理使用环境变量，不仅能提升项目的可维护性，更能从根本上避免敏感信息泄露。记住这一黄金法则：
“暴露给前端的，必须是无害的；敏感的，永远留在构建层。”
掌握这些要点，你就能在 Vite 项目中安全、高效地管理多环境配置，告别硬编码和配置混乱！
