Vite 系列课程 | 8. Vite 环境变量配置

8. Vite 环境变量配置

8.1 环境变量的概念：适应不同环境

环境变量是指在不同代码环境下，变量值可能会有所不同的情况。常见的代码环境包括：

• 开发环境 (Development)
• 测试环境 (Test/Staging)
• 预发布环境 (Pre-production/Beta)
• 生产环境 (Production)

• 开发和测试环境：http://test.api/
• 生产环境：https://api.example.com/

使用环境变量可以灵活配置这些值，避免在代码中硬编码，提高代码的可维护性和可移植性。

8.2 Vite 环境变量处理原理：安全且灵活

Vite 使用 dotenv 库来加载环境变量，但它并没有直接将所有环境变量注入到 process.env 中，而是通过以下方式进行处理，以提高安全性：

疑问：Vite 如何将变量注入到 import.meta.env 中？

Vite 在构建过程中会将 .env 文件中以 VITE_ 开头的变量转换为静态替换。例如，如果 .env 文件中有 VITE_API_URL=https://api.example.com，那么在构建后的代码中，import.meta.env.VITE_API_URL 会被直接替换为字符串 "https://api.example.com"。

8.3 配置相关的关键项：root 和 envDir

• root： 定义项目的根目录。默认为 process.cwd()，即当前工作目录。
• envDir： 配置 .env 文件的搜索目录。默认为项目根目录。

8.3.1 loadEnv 方法：手动加载环境变量

loadEnv 方法允许手动加载环境变量文件。它接受三个参数：

• mode：当前模式。
• dir：.env 文件的搜索目录。默认为 process.cwd()。
• prefix：环境变量前缀。默认为 VITE_。

import { defineConfig, loadEnv } from 'vite';

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd()); // 使用默认前缀 VITE_
  console.log('VITE_API_URL:', env.VITE_API_URL);
  return {
    // ...
  };
});

8.3.2 process.cwd() 方法：获取当前工作目录

8.4 Vite 环境变量的设置与使用：核心步骤

8.4.1 设置环境变量：使用 .env 文件

例如，在 .env.development 文件中：

VITE_API_URL=http://localhost:3000/api
VITE_APP_TITLE=My Development App

在 .env.production 文件中：

VITE_API_URL=https://api.example.com
VITE_APP_TITLE=My Production App

8.4.2 import.meta.env 与 vite.config.js：区分环境

• import.meta.env： 用于客户端代码中访问环境变量。
• vite.config.js： 在 Node.js 环境中运行，不能直接使用 import.meta.env。需要使用 loadEnv 方法加载环境变量。

示例：在 vite.config.js 中使用 loadEnv：

import { defineConfig, loadEnv } from 'vite';

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd());
  return {
    define: {
      __APP_VERSION__: JSON.stringify("1.0.0"), // Example of defining a constant
      __API_URL__: JSON.stringify(env.VITE_API_URL), // access the env variable
    },
    // ...
  };
});

注意： 上面的例子展示了如何在vite.config.js中使用loadEnv加载环境变量，并将其定义为常量，以便在客户端代码中使用。直接在vite.config.js中使用import.meta.env是不行的。

8.4.2.1 通过 process.env 访问系统环境变量

可以通过 process.env 访问系统环境变量，但这通常不推荐用于配置应用程序特定的环境变量，因为它可能会与其他工具或环境产生冲突。

8.4.2.2 使用 loadEnv 访问环境变量

loadEnv 是推荐的方式，因为它允许根据 mode 加载不同的 .env 文件，并使用指定的前缀，避免命名冲突。

8.5 修改 Mode 和环境变量前缀：更灵活的配置

8.5.1 修改 Mode：控制构建环境

通过命令行参数 --mode 可以指定 Vite 的运行模式：

• npm run dev -- --mode development
• npm run build -- --mode production
• npm run build -- --mode staging (需要创建 .env.staging 文件)

8.5.2 修改环境变量前缀：避免命名冲突

可以通过 vite.config.js 中的 envPrefix 选项修改环境变量前缀：

import { defineConfig } from 'vite';

export default defineConfig({
  envPrefix: 'APP_', // 修改前缀为 APP_
});

然后，在 .env 文件中使用新的前缀：

APP_API_URL=https://api.example.com

8.6 添加 Test 环境：扩展环境配置

创建 .env.test 文件来配置测试环境特定的变量。然后在 package.json 中添加一个 test 脚本：

"scripts": {
  "test": "vite build --mode test" // 或者 "vite dev --mode test" 用于开发服务器
}

8.7 补充：vite.config.js 的 ES Module 语法

vite.config.js 可以使用 ES Module 语法，是因为 Vite 在内部会使用 Node.js 的 ES Module 支持或将其转换为 CommonJS 格式。这使得配置文件的编写更加现代化。