在前端项目开发过程中，我们常常需要面对开发、测试、预发布、生产等多种环境。不同环境下，项目的配置往往存在差异，比如接口地址、静态资源路径、日志级别等。如果每次切换环境都手动修改配置，不仅效率低下，还容易出错。Vite 作为当下流行的前端构建工具，提供了便捷的多环境配置方案，能够帮助我们轻松应对不同环境的配置需求。

1. 环境变量文件

Vite 通过环境变量文件来区分不同环境的配置，这些文件需要遵循特定的命名规则，以便 Vite 能够正确识别和加载。
在项目根目录下，我们可以创建以下几种环境变量文件：

• .env：这是所有环境都会加载的基础配置文件，里面可以存放一些通用的环境变量。
• .env.local：同样会被所有环境加载，但该文件不会被 Git 跟踪，适合存放一些本地的私密配置，比如个人的开发密钥等。
• .env.[mode]：仅在指定模式（mode）下加载的配置文件。其中，[mode]可以是我们自定义的环境名称，如development（开发环境）、staging（预发布环境）、production（生产环境）等。
• .env.[mode].local：仅在指定模式下加载，且不会被 Git 跟踪，用于存放对应模式下的私密配置。

环境加载优先级官网说明：

• 指定模式的文件（例如 .env.production）会比通用文件的优先级更高（例如 .env）;
• 指定模式文件中声明的变量优先级高于通用文件中的变量，但仅在 .env 或 .env.local 中定义的变量仍然可以在环境中使用；
• Vite 执行时已经存在的环境变量有最高的优先级，不会被 .env 类文件覆盖。例如当运行 VITE_SOME_KEY=123 vite build 的时候;
• .env 类文件会在 Vite 启动一开始时被加载，而改动会在重启服务器后生效。

2. 环境变量与内置变量

2.1. 环境变量

Vite 自动将环境变量暴露在 import.meta.env 对象下，作为字符串。
为了防止意外地将一些环境变量泄漏到客户端，只有以 VITE_ 为前缀的变量才会暴露给经过 vite 处理的代码。例如下面这些环境变量：

1
2

VITE_SOME_KEY=123
DB_PASSWORD=foobar

只有 VITE_SOME_KEY 会被暴露为 import.meta.env.VITE_SOME_KEY 提供给客户端源码，而 DB_PASSWORD 则不会。

1
2

console.log(import.meta.env.VITE_SOME_KEY) // "123"
console.log(import.meta.env.DB_PASSWORD) // undefined

如果你想要自定义环境变量的前缀，请参阅 envPrefix 选项。

2.2. 内置变量

一些内置常量在所有情况下都可用：

• import.meta.env.MODE: {string} 应用运行的模式。
• import.meta.env.BASE_URL: {string} 部署应用时的基本 URL。他由base 配置项决定。
• import.meta.env.PROD: {boolean} 应用是否运行在生产环境（使用 NODE_ENV=’production’ 运行开发服务器或构建应用时使用 NODE_ENV=’production’ ）。
• import.meta.env.DEV: {boolean} 应用是否运行在开发环境 (永远与 import.meta.env.PROD相反)。
• import.meta.env.SSR: {boolean} 应用是否运行在 server 上。

在开发环境测试内置变量输出内容：

1
2
3
4
5

import.meta.env.MODE  // development
import.meta.env.BASE_URL // /
import.meta.env.PROD // false
import.meta.env.DEV // true
import.meta.env.SSR // false

3. 配置文件使用环境变量

3.1. vite.config.js配置

Vite 的配置文件vite.config.js是实现多环境配置的核心。我们可以在这个文件中通过loadEnv函数读取环境变量，并根据不同的环境对项目进行配置。
首先，需要从vite中导入defineConfig和loadEnv函数。defineConfig用于定义 Vite 的配置，loadEnv用于加载环境变量。

1

import { defineConfig, loadEnv } from 'vite'

然后，使用defineConfig函数导出一个配置对象，该对象可以是一个函数，接收一个包含mode等信息的参数。在函数内部，我们通过loadEnv函数加载当前模式下的环境变量。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

export default defineConfig(({ mode }) => {
  // 加载当前模式下的环境变量，第二个参数为环境变量文件所在的目录，这里使用项目根目录
  const env = loadEnv(mode, process.cwd())
  
  return {
    // 配置项目的基础路径，从环境变量中获取
    base: env.VITE_BASE_URL,
    // 开发服务器配置
    server: {
      // 开发环境下的端口号
      port: 8080,
      // 代理配置，解决跨域问题，接口地址从环境变量中获取
      proxy: {
        '/api': {
          target: env.VITE_API_URL,
          changeOrigin: true
        }
      }
    },
    // 其他配置...
  }
})

通过这样的配置，Vite 会根据不同的环境模式，加载对应的环境变量，并将这些变量应用到项目的配置中。

3.2. package.json配置

为了方便在不同环境下进行开发和构建，我们可以在package.json文件中设置相应的命令脚本，通过--mode参数指定环境模式。

1
2
3
4
5
6
7
8
9

{
  "scripts": {
    "dev": "vite --mode development", // 开发环境，默认模式可以省略--mode development
    "build:staging": "vite build --mode staging", // 预发布环境构建
    "build:production": "vite build --mode production", // 生产环境构建
    "preview:staging": "vite preview --mode staging", // 预发布环境预览
    "preview:production": "vite preview --mode production" // 生产环境预览
  }
}

这样，当我们执行npm run dev命令时，Vite 会以开发模式启动开发服务器，加载.env、.env.local、.env.development、.env.development.local等文件中的环境变量。执行npm run build:staging命令时，会以预发布模式进行构建，加载对应的环境变量文件。

3.3. loadEnv函数

1

loadEnv(mode: string, envDir: string, prefixes: string | string[] = 'VITE_'): Record<string, string>

• mode：环境模式，像 development、production 等；
• envDir：环境变量文件所在的目录，一般就是项目的根目录；
• prefixes：可选参数，用于过滤环境变量的前缀，默认是 VITE_；

4. 客户端代码使用环境变量

在客户端代码中，我们可以通过import.meta.env对象访问环境变量。例如：

1
2
3
4
5
6
7
8
9

// 获取接口地址
const apiUrl = import.meta.env.VITE_API_URL;
// 获取基础路径
const baseUrl = import.meta.env.VITE_BASE_URL;

// 使用接口地址发送请求
fetch(`${apiUrl}/data`)
  .then(response => response.json())
  .then(data => console.log(data));

5. 总结

Vite 的多环境配置通过环境变量文件、配置文件和命令脚本的配合，实现了对不同环境下项目配置的灵活管理。合理使用这些功能，能够提高开发效率，减少因环境配置问题导致的错误。
在实际项目开发中，我们可以根据项目的具体需求，制定适合的环境变量和配置方案，减少手动修改配置，让项目在不同的环境中都能稳定、高效地运行。