Vite 环境变量配置详解及最佳实践

在现代前端工程化开发中，环境变量（Environment Variables）是管理不同部署环境（开发、测试、预发、生产）配置的核心机制。Vite 作为新一代构建工具，对环境变量提供了简洁而强大的支持。

本文将深入讲解Vite 环境变量的加载规则、作用域、安全机制、自定义前缀配置、类型支持及最佳实践，助你写出安全、灵活、可维护的项目配置。

一、Vite 环境变量基础

🔑 核心规则

1. 只有带有指定前缀的变量才会暴露给客户端源码；
2. 在代码中通过import.meta.env访问；
3. 环境变量文件需放在项目根目录；
4. 支持多环境配置（.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=abc123

console.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影响：

五、在 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 项目中安全、高效地管理多环境配置，告别硬编码和配置混乱！