Vite无法加载.env文件中定义的环境变量求助

问题回顾 #

• 环境：React + TypeScript + Vite + Yarn
• 根目录.env定义VITE_BACKEND_URL=http://localhost:8080，但项目中无法读取，前端始终请求自身端口3036
• 尝试过：添加VITE_前缀、配置vite.config.ts的loadEnv和define，均无效
• 仅通过命令行传参（如VITE_BACKEND_URL=http://localhost:8080 yarn dev）能正常获取变量
• 终端执行source .env后能看到变量，但项目内process.env.VITE_BACKEND_URL和import.meta.env.VITE_BACKEND_URL均返回undefined

分步解决方案 #

1. 简化并修正vite.config.ts配置 #

Vite默认会自动加载根目录下带VITE_前缀的环境变量，无需手动通过define注入，反而手动配置容易出错。修改后的配置如下：

import { defineConfig, loadEnv } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig(({ mode }) => {
  // 加载对应mode的环境变量，第三个参数设为''可加载所有变量（包括非VITE_前缀的）
  const env = loadEnv(mode, process.cwd(), '')
  
  return {
    plugins: [react()], // 确保添加React插件（未安装则执行yarn add @vitejs/plugin-react -D）
    // 其他Vite配置...
  }
})

2. 正确读取环境变量（改用import.meta.env） #

Vite中前端代码不能直接使用process.env（这是Node.js环境变量），Vite默认将环境变量注入到import.meta.env中。修改你的环境变量读取文件：

// 环境变量读取文件
const env = {
  NODE_ENV: import.meta.env.NODE_ENV || 'development',
  BACKEND_URL: import.meta.env.VITE_BACKEND_URL,
};

export type ProjectEnv = typeof env;

export default () => ({
  data: env,
});

3. 修复TypeScript类型提示（解决import.meta.env未定义问题） #

在项目根目录创建src/vite-env.d.ts文件，添加以下类型声明：

/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_BACKEND_URL: string;
  readonly NODE_ENV: string;
  // 其他需要的环境变量可在此添加
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

这个文件会告诉TypeScriptimport.meta.env包含的变量，避免类型报错。

4. 确保.env文件的正确性 #

• 文件必须放在项目根目录（与vite.config.ts同级）
• 变量名必须以VITE_开头（如VITE_BACKEND_URL）
• 变量值前后不要加引号（正确写法：VITE_BACKEND_URL=http://localhost:8080）

5. 重启开发服务器 #

修改.env或vite.config.ts后，必须重启yarn dev，否则新配置不会生效。

6. 修正Axios客户端的变量引用 #

确保BuildConfig.BACKEND_URL指向正确的环境变量来源，比如：

// 导入环境变量
import envConfig from './path/to/your/env/file'; // 替换为实际文件路径

export const baseClient = (
  accessToken?: string | null,
  baseURL: string = '',
): AxiosInstance => {
  const headers: Record<string, string> = {};

  if (accessToken) {
    headers.Authorization = `Bearer ${accessToken}`;
  }

  return axios.create({
    baseURL: isURL(envConfig.data.BACKEND_URL) ? envConfig.data.BACKEND_URL : baseURL,
    headers,
    transformResponse: [maybeParseJSON],
  });
};

为什么之前的配置无效？ #

1. 手动define配置错误：之前的define直接写VITE_BACKEND_URL: JSON.stringify(env.VITE_BACKEND_URL)，但代码是从process.env读取，正确写法应为'process.env.VITE_BACKEND_URL': JSON.stringify(env.VITE_BACKEND_URL)，但这种方式不如Vite原生的import.meta.env推荐。
2. 使用process.env错误：前端代码运行在浏览器中，没有Node.js的process对象，Vite不会默认将环境变量注入到process.env。
3. 缺少TypeScript类型声明：导致import.meta.env被TypeScript识别为未定义，无法正常使用。

内容的提问来源于stack exchange，提问作者user20134455