Vite 环境变量为什么在配置加载时取不到

在 vite.config.* 里直接读取 process.env.MY_KEY，却发现同名变量写在 .env 中，这种结果通常不是变量名拼错，而是读取时机不同。Vite 会先求值用户配置，再根据配置中的 root、envDir 和最终 mode 决定要加载哪些环境文件。因此，配置文件运行时只有当前进程已经拥有的环境变量。

需要让 .env* 参与配置决策时，在配置函数里拿到 mode，显式调用 loadEnv(mode, root, '')；只给前端业务代码使用的变量，则继续在业务模块中读取 import.meta.env。

配置加载早于 .env 文件解析

Vite 的配置可能改变环境文件的查找目录，模式也会决定是否读取 .env.production 或 .env.staging。如果它在执行配置之前就把所有环境文件塞进 process.env，反而无法先确定正确的目录和模式，所以默认策略是先加载配置、后加载环境文件。

这也解释了两个看似矛盾的现象：同一个变量在组件中通过 import.meta.env.VITE_API_BASE 能读到，在 vite.config.ts 中直接访问却是 undefined；而在命令行写成 VITE_API_BASE=... 后，配置里的 process.env.VITE_API_BASE 又能读到。后者属于启动进程本来就拥有的变量。

用 loadEnv 让配置参与端口和插件决策

官方地址：https://vite.dev/config/

把配置导出为函数，就可以同时拿到当前 mode。下面的写法读取项目根目录下与模式匹配的文件，并把端口从字符串转换成数字：

import { defineConfig, loadEnv } from 'vite'

export default defineConfig(({ mode }) => {
  // 按当前 mode 读取 .env、.env.local 和 .env.[mode] 文件。
  // 空前缀表示配置阶段也允许读取不带 VITE_ 的变量。
  const env = loadEnv(mode, process.cwd(), '')
  const port = Number(env.APP_PORT || 5173)

  return {
    // 配置字段需要数字，不能直接把环境变量字符串传进去。
    server: { port: Number.isFinite(port) ? port : 5173 },
    define: {
      // 只把明确允许进入前端代码的值暴露为常量。
      __APP_ENV__: JSON.stringify(env.APP_ENV || mode),
    },
  }
})

如果变量位于自定义目录，应把第二个参数换成实际的 root 或 envDir 对应路径；否则你可能以为文件没有加载，实际是查错了目录。若只想读取客户端变量，也可以把第三个参数写成 'VITE_'，但配置端口、代理地址等常常不应被这个前缀限制。

三个环境变量入口不要混用

尤其要留意 VITE_API_URL 和 DB_PASSWORD 的差别：前者适合公开的接口地址，后者即使写在 .env 中，也不应通过 VITE_ 前缀暴露。前端代码本身无法保守保存真正的服务端秘密。

配置里仍为空时按这张清单排查

1. 确认命令使用的模式：vite build 默认是 production，临时环境要明确写 --mode staging。
2. 确认文件名和目录：模式文件必须是 .env.[mode]，自定义 envDir 后不要继续只查项目根目录。
3. 确认优先级：命令行已有的环境变量不会被 env 文件覆盖；改完 env 文件后要重启开发服务器。
4. 确认类型：端口、布尔开关和数组都要在配置函数里显式转换，不能把字符串 "false" 当作布尔值。

如果页面读取不到变量，再检查是否写了 VITE_ 前缀；如果配置读取不到，则先检查是否调用了 loadEnv，以及它的 mode 和目录参数是否准确。

常见问题

为什么 .env 中的变量在配置文件里是 undefined？

因为配置求值发生在 Vite 自动加载 env 文件之前。使用 loadEnv(mode, root, '')，不要只改变量名。

loadEnv 读取到的端口为什么不能直接使用？

环境变量解析结果是字符串，应该用 Number() 转换，并对无效值提供回退。

所有变量都加 VITE_ 能解决问题吗？

不能。它只能帮助客户端代码读取，却会把值打进浏览器端产物，不适合密码、私钥和内部凭据。