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

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

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

---

一、Vite 环境变量基础

🔑 核心规则

1. 只有带有指定前缀的变量 才会暴露给客户端源码；
2. 在代码中通过 import.meta.env 访问；
3. 环境变量文件需放在项目根目录；
4. 支持多环境配置（.env.development, . .env.production` 等）。

⚠️ 安全设计 ：未匹配前缀的变量不会被打包到客户端代码中，避免敏感信息泄露。

---

二、环境变量前缀：默认与自定义

默认前缀：VITE_

Vite 默认只将 以 VITE_ 开头 的环境变量注入到客户端代码中：

# .env
VITE_API_BASE=https://api.example.com   # ✅ 会暴露
DB_PASSWORD=secret123                   # ❌ 不会暴露

// src/main.js
console.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.js
import { defineConfig } from 'vite';

export default defineConfig({
  envPrefix: 'MYAPP_', // 使用单个自定义前缀
});

或者支持多个前缀：

export default defineConfig({
  envPrefix: ['MYAPP_', 'COMPANY_'], // 数组形式支持多个前缀
});

配置后，只有以 MYAPP_ 或 COMPANY_ 开头的变量才会被注入：

# .env
MYAPP_THEME=dark
COMPANY_LOGO_URL=/logo.png
SECRET_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/ 目录下）

// 访问自定义前缀变量
const apiUrl = import.meta.env.MYAPP_API_URL;

// 使用内置布尔变量（不受 envPrefix 影响）
if (import.meta.env.DEV) {
  console.log('Running in development mode');
}

// 注意：所有值都是字符串！
const enableFeature = 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.js
export default defineConfig({
  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" />

interface ImportMetaEnv {
  readonly MYAPP_API_URL: string;
  readonly MYAPP_ENABLE_ANALYTICS: string;
  readonly MYAPP_VERSION: string;
  // 添加你实际使用的变量
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

之后在 TypeScript 文件中即可享受自动补全和类型校验：

// ✅ 类型安全
const url = 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 项目中安全、高效地管理多环境配置，告别硬编码和配置混乱！