解决 Property 'env' does not exist on type 'ImportMeta'.ts(2339) 错误

问题描述

在使用 Vite + Vue.js/React 开发项目时，当在代码中使用 import.meta.env 访问环境变量（如 import.meta.env.BASE_URL）时，开发环境正常运行，但在执行 npm run build 时出现错误：
Property 'env' does not exist on type 'ImportMeta'.ts(2339)

常见表现为：

• 开发环境 (npm run dev) 工作正常
• 构建环境 (npm run build) 抛出 TS2339 类型错误
• 即使已在 env.d.ts 中声明接口，问题仍然存在

根本原因

该错误是由于 TypeScript 无法正确识别 Vite 提供的 ImportMetaEnv 类型定义导致的，通常由以下原因引起：

1. 缺少类型声明引用：Vite 的新版本需要额外的类型声明
2. 声明文件未被包含：env.d.ts 未被正确包含在 TypeScript 编译上下文中
3. 多个 tsconfig 文件冲突：项目中的多个 TS 配置文件存在冲突设置

---

解决方案

✅ 解决方案一：添加必需的 Vite 类型引用 (推荐)

在 vite-env.d.ts 中添加对 vite/types/importMeta.d.ts 的引用：

/// <reference types="vite/client" />
/// <reference types="vite/types/importMeta.d.ts" /> // 添加这行

验证步骤：

1. 确保文件位于 src/ 目录下
2. 检查文件是否包含上述两行引用
3. 重启 TypeScript 服务器（通常重启编辑器或运行终端）

✅ 解决方案二：正确声明 ImportMeta 接口

在 src/vite-env.d.ts 中明确定义环境变量类型：

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

interface ImportMetaEnv {
  readonly BASE_URL: string;
  readonly VITE_API_URL: string; // 你的自定义变量
  // 添加其他需要的环境变量...
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

✅ 解决方案三：确保声明文件包含在 TS 配置

在 tsconfig.json 或 tsconfig.app.json 中包含声明文件：

{
  "include": [
    "src/vite-env.d.ts", // 确保包含此文件
    "src/**/*.ts",
    "src/**/*.tsx",
    "src/**/*.vue"
  ]
}

✅ 解决方案四：检查并修复 tsconfig 冲突

检查 tsconfig.vitest.json 和其他 tsconfig 文件，避免过度限缩 include 范围：

{
  // 不要限定仅测试文件
  "include": ["tests/**/*.ts", "src/**/*.vue", "src/**/*.ts"]
}

---

完整配置示例

1. 环境声明文件

/// <reference types="vite/client" />
/// <reference types="vite/types/importMeta.d.ts" />

interface ImportMetaEnv {
  readonly BASE_URL: string;
  readonly VITE_API_KEY: string;
  // 其他自定义环境变量...
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

2. TypeScript 配置

{
  "compilerOptions": {
    "types": ["vite/client", "vitest/globals"],
    // 其他配置...
  },
  "include": ["src/vite-env.d.ts", "src/**/*"],
  // exclude
}

3. 访问环境变量

在代码中安全访问：

// 正确访问BASE_URL
const baseUrl = import.meta.env.BASE_URL;

// 访问自定义变量（必须以VITE_开头）
const apiKey = import.meta.env.VITE_API_KEY;

---

可能遇到的问题排查

1. 文件位置错误：

   • ❌ vite-env.d.ts 位于项目根目录
   • ✅ 应移动到 src/ 目录下

2. 缺少 types 定义：

   {
     "compilerOptions": {
       "types": ["vite/client"] // 必须有此项
     }
   }

3. 多个配置冲突：

   # 快速检查配置
   npx tsc --showConfig

4. Vite 版本问题：

   • Vite v4+ 需要双重引用声明解决方案
   • 升级命令：npm install vite@latest

临时解决方案（不推荐）

仅在测试或紧急情况下使用：

// @ts-expect-error // 忽略类型错误
const baseUrl = import.meta.env.BASE_URL;

警告：这仅是临时解决方案，会掩盖实际类型问题

结论

通过组合使用以下方法可永久解决此问题：

1. 在 vite-env.d.ts 中添加双重类型引用
2. 正确定义 ImportMetaEnv 接口
3. 确保声明文件包含在 tsconfig include 中
4. 检查并修复多个 tsconfig 文件冲突

完成上述配置后，npm run build 应能成功执行，不再出现 TS2339 类型错误。