Vite项目中vite.config.js中为什么只能使用process.env，无法使用import.meta.env？

关键要点

• 研究表明，Vite 配置文件（vite.config.js）运行在 Node.js 环境中，因此只能使用 process.env 访问环境变量，而 import.meta.env 专为客户端代码设计，在配置文件中不可用。
• 于建议在 vite.config.js 中使用 process.env 来配置构建过程，在客户端代码中使用 import.meta.env 访问以 VITE_ 开头的环境变量。
• 存在争议：一些开发者可能尝试在配置文件中使用 import.meta.env，但这会导致错误，因为它不适用于 Node.js 环境。

---

为什么 vite.config.js 只能使用 process.env？

什么是 process.env 和 import.meta.env？
process.env 是 Node.js 的全局对象，用于访问环境变量，适用于服务器端脚本，如 Vite 的配置文件。
import.meta.env 是 Vite 为客户端代码提供的特性，允许在浏览器环境中访问以 VITE_ 开头的环境变量。

为什么不能在 vite.config.js 中使用 import.meta.env？
Vite 的配置文件运行在 Node.js 环境中，而 import.meta.env 专为客户端代码设计，因此在配置文件中不可用。尝试使用 import.meta.env 会导致错误，因为它在 Node.js 环境中未定义。

使用场景示例

• 在 vite.config.js 中使用 process.env：
  假设你想根据环境变量设置构建输出目录：

  import { defineConfig } from 'vite'
  
  export default defineConfig({
    build: {
      outDir: process.env.OUT_DIR || 'dist'
    }
  })
  

  这里，process.env.OUT_DIR 用于动态配置输出目录。

• 在客户端代码中使用 import.meta.env：
  在你的应用代码中，可以这样访问环境变量：

  console.log(import.meta.env.VITE_API_URL)
  

  这会输出 VITE_API_URL 的值，但前提是它在 .env 文件中以 VITE_ 开头。

意外的细节
你可能以为 import.meta.env 在配置文件中也能工作，因为两者都涉及环境变量，但实际上它们的适用范围完全不同：process.env 适用于服务器端，import.meta.env 适用于客户端。

---

详细解释 vite.config.js 中 process.env 和 import.meta.env 的使用

背景与原理

Vite 是一个现代前端构建工具，旨在提供快速的开发体验和高效的构建过程。其配置文件（通常为 vite.config.js）允许开发者自定义构建行为，而环境变量是配置过程中的关键部分。process.env 是 Node.js 的标准特性，用于访问环境变量，而 import.meta.env 是 Vite 专为客户端代码设计的特性，用于在浏览器环境中访问环境变量。

具体来说，vite.config.js 运行在 Node.js 环境中，因此可以直接使用 process.env 访问任何环境变量。相反，import.meta.env 是 Vite 在构建过程中注入到客户端代码中的，旨在提供安全的环境变量访问，仅暴露以 VITE_ 开头的变量，以防止敏感信息泄露。因此，在 vite.config.js 中尝试使用 import.meta.env 会导致错误，因为它在 Node.js 环境中未定义。

功能与机制

• process.env：这是 Node.js 的全局对象，包含进程的环境变量。在 vite.config.js 中，Vite 会加载 .env 文件中的变量到 process.env，开发者可以直接访问。例如：

  • 如果 .env 文件中有 OUT_DIR=build，则在 vite.config.js 中可以写 process.env.OUT_DIR 来获取 “build”。
  • 这适用于配置构建输出目录、端口号等服务器端设置。

• import.meta.env：这是 Vite 为客户端代码提供的特性。在构建过程中，Vite 会将 import.meta.env.VARIABLE_NAME 替换为对应的环境变量值，但仅限于以 VITE_ 开头的变量。例如：

  • 如果 .env 文件中有 VITE_API_URL=http://api.com，则在客户端代码中 import.meta.env.VITE_API_URL 会是 “http://api.com”。
  • 这适用于需要在浏览器中动态配置 API 端点、调试标志等。

由于 vite.config.js 是 Node.js 脚本，import.meta.env 在此环境中不可用。如果尝试在配置文件中写 console.log(import.meta.env)，会抛出错误，因为 import.meta.env 未定义。

实际使用场景与示例

以下是几个实际使用场景，并结合代码说明：

1. 配置构建输出目录
   假设你想根据环境变量设置构建输出目录：

   // vite.config.js
   import { defineConfig } from 'vite'
   
   export default defineConfig({
     build: {
       outDir: process.env.OUT_DIR || 'dist'
     }
   })
   

   这里，process.env.OUT_DIR 用于动态设置输出目录。如果尝试用 import.meta.env.OUT_DIR，会报错。

2. 传递环境变量到客户端
   在客户端代码中，你可能需要访问 API 端点：

   // src/main.js
   console.log(import.meta.env.VITE_API_URL)
   

   但在 vite.config.js 中，如果你想基于同样的环境变量做配置，必须用 process.env.VITE_API_URL，例如：

   // vite.config.js
   import { defineConfig } from 'vite'
   
   export default defineConfig({
     define: {
       'process.env.VITE_API_URL': JSON.stringify(process.env.VITE_API_URL)
     }
   })
   

   这里，process.env.VITE_API_URL 被用作配置的一部分。

3. 加载 .env 文件中的变量
   Vite 使用 dotenv 自动加载 .env 文件中的变量到 process.env，因此在 vite.config.js 中可以直接访问。例如：

   • .env 文件中有 PORT=3000，则 process.env.PORT 在配置文件中可用。
   • 但在客户端代码中，只有 VITE_PORT=3000 才会通过 import.meta.env.VITE_PORT 暴露。

最佳实践与注意事项

尽管 process.env 在 vite.config.js 中可用，但需要注意以下几点：

• 安全性：确保不将敏感信息（如数据库密码）通过 process.env 暴露到客户端。如果需要传递到客户端，必须通过 define 选项手动设置，并确保值安全。
• 前缀规则：客户端代码只能访问以 VITE_ 开头的变量，这是 Vite 的安全机制。
• 动态性：process.env 的值在运行时固定，而 import.meta.env 的值在构建时由 Vite 处理。

以下是 process.env 与 import.meta.env 的对比表：

特性	process.env	import.meta.env
适用环境	Node.js（服务器端）	浏览器（客户端）
访问方式	process.env.VARIABLE_NAME	import.meta.env.VITE_VARIABLE
暴露规则	所有环境变量	仅 VITE_ 前缀变量
安全性	需要手动确保不泄露	自动过滤，非 VITE_ 不暴露
使用场景	构建配置、服务器逻辑	客户端动态配置

争议与复杂性

使用 process.env 和 import.meta.env 存在一些争议，主要围绕它们的适用范围。一些开发者可能误以为 import.meta.env 在配置文件中也能工作，导致错误。研究表明，Vite 社区倾向于明确区分两者的使用场景：process.env 用于服务器端配置，import.meta.env 用于客户端代码。这种区分有助于减少混淆，但也增加了学习成本，尤其对新手开发者。

结论

综上所述，vite.config.js 只能使用 process.env 访问环境变量，因为它运行在 Node.js 环境中，而 import.meta.env 是专为客户端代码设计的特性，不适用于配置文件。通过合理使用 process.env 配置构建过程，并通过 import.meta.env 在客户端访问环境变量，可以最大化利用 Vite 的现代化特性，同时确保安全性和可维护性。

---

关键引文

• Env Variables and Modes Vite 官方文档
• How to load environment variables from .env file using Vite Stack Overflow
• Why did vite select import.meta.env for providing environment variables? Vite GitHub Discussion