React TypeScript项目迁移Vite后类型声明文件最优组织方式

核心逻辑 #

/// <reference types="vite/client" /> 的作用是让 TypeScript 识别 Vite 提供的全局类型（如 ImportMeta、import.meta.env、.vue/.svg 等模块类型），重复引用完全多余，只需保留一处即可。

优化方案 #

• 保留 env.d.ts 中的引用，删除 types/global.d.ts 里的重复引用
  原因：env.d.ts 本身就是用来扩展 Vite 的 ImportMetaEnv 类型的，将 Vite 类型引用放在这里逻辑更统一，也能确保环境变量的类型扩展依赖正确的基础类型。

• 确保 TypeScript 配置能正确识别声明文件
  检查 tsconfig.json 的 include 字段，确保包含你的声明文件路径：

  {
    "compilerOptions": {
      // 其他配置...
    },
    "include": ["src/**/*", "types/**/*.d.ts", "env.d.ts"]
  }
  

  如果 env.d.ts 放在 types 目录下，只需保留 "types/**/*.d.ts" 即可，无需单独声明。

优化后的 env.d.ts 示例 #

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

interface ImportMetaEnv {
  readonly VITE_MY_ENDPOINT: string;
  // 更多环境变量...
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

补充说明 #

如果 types/global.d.ts 中包含其他全局类型声明（如自定义全局变量、接口），完全不受影响，去掉重复的 Vite 类型引用后，TS 会通过 env.d.ts 的引用来加载所有 Vite 相关类型。

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