React/Vite无法加载env.local环境变量问题求助

以下是几个排查和解决的关键点：

• 确认env.local的位置：必须放在项目根目录（和vite.config.ts、package.json同层级），不能放在src或其他子文件夹里。
• 检查env.local格式：变量名和值之间不要加空格，也不要给值加引号，正确格式如下：

  VITE_API_URL=http://120.0.0.1:8080
  

• 修正loadEnv的路径：把process.cwd()换成__dirname，__dirname指向当前vite.config.ts所在的目录，比process.cwd()更可靠（如果在子目录执行启动命令，process.cwd()会出错）。
• 重启开发服务器：修改.env文件后必须重启Vite服务器，否则新的环境变量不会生效。
• 检查运行模式：执行npm run dev时mode默认是development，Vite会加载.env.development和.env.local；执行npm run build时mode是production，要确保对应的env文件里有VITE_API_URL。
• 排查变量覆盖问题：如果存在.env.development文件，里面的VITE_API_URL会被.env.local覆盖，但.env里的变量优先级最低，确认没有其他env文件的变量干扰。

修改后的完整vite.config.ts代码：

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import path from 'path';
import { TanStackRouterVite } from '@tanstack/router-vite-plugin';
import { loadEnv } from 'vite';

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, __dirname, '');

  if (!env.VITE_API_URL) {
    throw new Error(`VITE_API_URL is not defined <${mode}> ${JSON.stringify(env)}`);
  }

  return {
    plugins: [TanStackRouterVite(), react()],
    base: '/app/',
    server: {
      proxy: {
        '/api': env.VITE_API_URL,
      },
    },
    resolve: {
      alias: {
        '@': path.resolve(__dirname, './src'),
      },
    },
    build: {
      sourcemap: true,
      outDir: 'build',
    },
  };
});

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