关于vite+vue3+ts项目中env.d.ts 文件详解

env.d.ts 文件是 Vite 项目中用于定义全局类型声明的 TypeScript 文件。它帮助开发者向 TypeScript提供全局的类型提示，特别是在使用一些特定于 Vite 的功能时（如 import.meta.env）。以下是详细讲解及代码示例

1. env.d.ts 文件的作用

• 全局类型声明：用于声明全局类型，例如 import.meta.env 的类型。
• 模块增强：为一些特殊的模块（如 *.svg、*.json 等）提供模块声明。
• 类型提示支持：帮助 TypeScript 理解 Vite 的环境变量或自定义模块。

2. Vite 环境变量

Vite 中的环境变量通常通过 import.meta.env 获取，如：

console.log(import.meta.env.VITE_API_URL);

为了让 TypeScript 正确识别这些变量，需要在 env.d.ts 中定义相应的类型。

3. 创建和配置 env.d.ts

步骤 1：创建 env.d.ts 文件

在项目的根目录下创建 env.d.ts 文件（通常与 tsconfig.json 同级）。

步骤 2：定义类型声明

以下是 env.d.ts 的一个常见配置：

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

interface ImportMetaEnv {
  readonly VITE_API_URL: string; // 定义一个自定义环境变量
  readonly VITE_APP_TITLE: string; // 定义另一个变量
  // 你可以根据需要添加更多变量
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

4. 代码示例

场景：使用环境变量

1. .env 文件内容

VITE_API_URL=https://api.example.com
VITE_APP_TITLE=My Vite App

2. env.d.ts 文件

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

interface ImportMetaEnv {
  readonly VITE_API_URL: string;
  readonly VITE_APP_TITLE: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

3. 在项目中使用环境变量

console.log("API URL:", import.meta.env.VITE_API_URL);
console.log("App Title:", import.meta.env.VITE_APP_TITLE);

4. 启动项目

运行 vite，控制台将输出：

API URL: https://api.example.com
App Title: My Vite App

5. 声明自定义模块

如果项目中使用了非 TypeScript 原生支持的模块（如 .svg 或 .json 文件），需要在 env.d.ts 中声明这些模块的类型。

代码示例：声明 .svg 模块

1. 在 env.d.ts 中添加声明

declare module "*.svg" {
  const content: string;
  export default content;
}

2. 在代码中使用

import logo from "./assets/logo.svg";

console.log("SVG Path:", logo);

6. 注意事项

1. 不要手动修改生成的 .d.ts 文件：例如 env.d.ts 是用来声明类型的，不用于编写业务逻辑代码。
2. 命名规范：确保变量名以 VITE_ 开头，这是 Vite 环境变量的要求。
3. 类型定义准确：尽量为每个变量定义明确的类型（如 string、number 等）。

7. 总结

env.d.ts 文件的核心是：

• 为 Vite 提供环境变量类型提示。
• 为自定义模块声明类型。
• 提高 TypeScript 的开发体验。

通过结合 .env 文件、env.d.ts 配置和 TypeScript 的强大能力，可以有效提升 Vite 项目的开发效率和代码质量。