从CRA迁移到Vite：.env文件配置及环境变量未定义问题排查

核心问题分析 #

报错vite-plugin-environment: the DOMAIN environment variable is undefined的原因通常是：

• .env文件中未正确定义DOMAIN变量
• Vite未加载到对应环境的.env文件
• 第三方插件配置未正确读取环境变量

推荐方案：使用Vite内置能力复刻配置 #

Vite自带.env加载机制，无需依赖第三方插件，完全可以复刻CRA+CRACO的.env配置逻辑：

1. 保持.env文件结构与CRA一致 #

在项目根目录下创建对应环境的.env文件，优先级与CRA一致：

• .env：通用配置，所有环境生效
• .env.development：开发环境专属配置
• .env.production：生产环境专属配置
• .env.local：本地私有配置（需添加到.gitignore）
• .env.development.local：开发环境本地私有配置

在对应文件中定义变量，比如.env.development：

DOMAIN=http://localhost:3000

2. 配置vite.config.js注入全局变量 #

通过Vite的loadEnv加载所有.env变量，再用define复刻webpack DefinePlugin的全局变量注入：

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

export default defineConfig(({ mode }) => {
  // 加载对应环境的所有.env变量（第三个参数设为空字符串，支持非VITE_开头的变量）
  const env = loadEnv(mode, process.cwd(), '')

  return {
    plugins: [react()],
    define: {
      // 注入全局变量，与CRA的DefinePlugin行为完全一致
      DEV: JSON.stringify(mode === 'development'),
      DOMAIN: JSON.stringify(env.DOMAIN),
      // 其他需要的全局变量可在此添加，比如API_URL: JSON.stringify(env.API_URL)
    }
  }
})

3. 验证配置有效性 #

在JSX中直接访问全局变量即可，无需额外导入：

function App() {
  return (
    <div>
      <p>当前环境域名：{DOMAIN}</p>
      <p>是否开发环境：{DEV ? '是' : '否'}</p>
    </div>
  )
}

备选方案：修复vite-plugin-environment报错 #

如果坚持使用vite-plugin-environment，需确保插件能读取到.env变量：

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

export default defineConfig(({ mode }) => {
  // 先手动加载.env变量到process.env
  const env = loadEnv(mode, process.cwd(), '')
  process.env = { ...process.env, ...env }

  return {
    plugins: [
      react(),
      EnvironmentPlugin({
        DOMAIN: process.env.DOMAIN,
        DEV: mode === 'development',
        // 若允许变量未定义，可添加allowUndefined: true（不推荐）
        // allowUndefined: true
      })
    ]
  }
})

关键注意事项 #

• 确保.env文件放置在项目根目录，而非src等子目录
• 变量名拼写需完全一致，注意大小写
• .local后缀的.env文件需添加到.gitignore，避免提交私有配置

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