生产环境使用import.meta.env致Vite应用崩溃的问题排查

问题描述 #

生产环境中使用import.meta.env相关代码（如：

const backendUrl = import.meta.env.VITE_BACKEND_URL;

）时，触发致命错误：

TypeError: Cannot read properties of undefined (reading 'VITE_BACKEND_URL').

vite.config.ts中通过loadEnv可正常读取环境变量，但应用代码中无法获取。

解决方案 #

• 检查环境变量文件配置
  确保生产环境的环境变量文件（如.env.production）放在项目根目录（与vite.config.ts同级），变量名严格以VITE_开头，无多余空格或语法错误，例如：

  VITE_BACKEND_URL=https://your-production-api.com
  

• 配置Remix插件暴露客户端环境变量
  Remix的Vite插件不会自动将所有VITE_开头的变量暴露给客户端，需在remix插件配置中显式声明要传递的变量：

  remix({
    appDirectory: 'app',
    buildDirectory: 'build',
    // 添加该选项指定客户端可访问的环境变量
    clientEnvironmentVariables: ['VITE_BACKEND_URL'],
  }),
  

• 确认生产构建的mode参数
  检查package.json中的build命令，确保指定了正确的mode：

  "scripts": {
    "build": "vite build --mode production"
  }
  

  错误的mode会导致Vite加载错误的环境变量文件，进而客户端无法获取变量。

• 验证构建产物的变量替换
  构建完成后，查看dist目录下的客户端JS文件，搜索VITE_BACKEND_URL，确认是否被替换为实际的环境变量值。若未替换，需检查变量名是否符合规范或配置是否生效。

• 补充TypeScript类型声明（可选）
  在vite-env.d.ts中添加类型声明，避免开发时的类型错误，同时确保Vite客户端类型被正确引入：

  /// <reference types="vite/client" />
  
  interface ImportMetaEnv {
    readonly VITE_BACKEND_URL: string;
  }
  
  interface ImportMeta {
    readonly env: ImportMetaEnv;
  }
  

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