Vite + React + TypeScript环境变量加载失败求助

核心问题分析 #

运行npm run dev时，loadEnv返回空对象，无法读取.env文件中的变量，大概率是配置加载时机、文件路径或语法规则问题导致。

解决方案步骤 #

1. 调整loadEnv调用时机（最可能解决问题） #

将loadEnv移至defineConfig的工厂函数内部，利用Vite自动传入的mode参数，避免手动硬编码模式引发的路径或加载时机错误：

修改vite.config.ts：

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

export default defineConfig(({ mode }) => {
  // 使用Vite传入的当前运行模式，而非硬编码'development'
  const env = loadEnv(mode, process.cwd(), 'VITE_');

  console.log('Env:', env);
  console.log('API URL:', env.VITE_API_URL);
  console.log("******************************");
  console.log('Current working directory:', process.cwd());
  console.log("******************************");

  return {
    plugins: [react()],
    server: {
      host: '0.0.0.0',
      port: 5173,
    },
    build: {
      target: 'esnext',
      minify: 'esbuild',
      lib: {
        entry: './src/index.tsx',
        formats: ['es'],
      },
    },
  };
});

2. 验证.env文件路径与命名 #

根据控制台打印的process.cwd()路径/home/jogugil/jogugil_projects/gochat/web，确认：

• .env文件直接放在该目录下（与vite.config.ts同目录）
• 文件名严格为.env，而非.env.dev、.env.local等（除非你需要对应模式的环境文件）
• 无文件名拼写错误，比如写成.env.或env

3. 检查.env文件语法 #

确保变量定义符合KEY=VALUE格式：

• 等号两边不要加空格（比如VITE_API_URL = xxx会导致读取失败）
• 值无需额外引号（除非值包含空格，例如VITE_APP_NAME="My App"）

你的.env文件目前格式正确，可跳过此步，但后续修改需注意规则。

4. 排查高优先级环境文件覆盖 #

Vite环境变量加载优先级为：.env.local > .env.[mode].local > .env.[mode] > .env。如果web目录下存在.env.local或.env.development.local，且文件中未定义目标变量，会覆盖.env的内容。可暂时重命名这些文件，测试是否能读取到.env的变量。

5. 验证客户端变量可用性 #

修复服务端加载后，在React组件中测试变量是否正常访问：

function App() {
  return (
    <div>
      <p>API URL: {import.meta.env.VITE_API_URL}</p>
    </div>
  );
}

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