Vue3中env.d.ts类型声明文件的作用与配置

在你开发 Vue 3 项目时，env.d.ts 文件（或者类似的 vite-env.d.ts 文件）是一个类型声明文件。它最大的作用是为你的代码提供 TypeScript 类型智能提示和类型检查，而不是一个会在应用程序运行时“执行”的文件。

它的工作时机是在 TypeScript 编译阶段，当你编写代码时，你的代码编辑器（如 VS Code）或构建过程（运行 vite build 或 vue-tsc）中的 TypeScript 语言服务会读取它，以确保你使用的环境变量具有正确的类型。

下面这个表格总结了相关文件在不同阶段的处理情况：

🔧 如何配置和使用 env.d.ts

为了让 env.d.ts 文件生效，你需要进行一些配置：

1. 文件位置和内容：该文件通常放在项目根目录或 src 目录下。一个基本的内容示例是：

   typescript

   /// <reference types="vite/client" />
   
   interface ImportMetaEnv {
     readonly VITE_APP_TITLE: string; // 为你自定义的环境变量定义类型
     readonly VITE_API_BASE_URL: string;
     // 更多环境变量...
   }
   
   interface ImportMeta {
     readonly env: ImportMetaEnv;
   }

   第一行 /// <reference types="vite/client" /> 非常重要，它确保了 Vite 默认环境变量（如 import.meta.env.MODE）的类型定义被包含进来。

2. TypeScript 配置：确保你的 tsconfig.json 或 tsconfig.app.json 文件包含了这个类型声明文件。

   json

   {
     "include": [
       "env.d.ts",
       "src/**/*.ts",
       "src/**/*.tsx",
       "src/**/*.vue"
     ]
   }

   如果 env.d.ts 文件不在根目录下，你需要根据实际情况调整 include 数组中的路径。

3. 在代码中使用：配置好后，你在代码中使用 import.meta.env 时，TypeScript 就能提供智能提示和类型检查了。

   typescript

   // 在Vue组件或TS文件中
   const apiUrl = import.meta.env.VITE_API_BASE_URL; // 有代码提示和类型检查
   console.log(import.meta.env.VITE_APP_TITLE); // 有代码提示和类型检查

⚠️ 注意区分环境变量文件

需要注意的是，定义环境变量值的是你的 .env 文件（例如 .env, .env.development, .env.production），而不是 env.d.ts 文件。

• .env 文件：这些文件在构建时被 Vite 读取，其中的环境变量被注入到应用中。默认情况下，只有以 VITE_ 开头的变量才会暴露给客户端代码。

  bash

  # .env.development
  VITE_API_BASE_URL=http://localhost:3000/api
  VITE_APP_TITLE=My App (Development)

• env.d.ts 文件：它为这些在构建时注入的变量提供类型信息，以便在开发阶段（编写代码时）获得更好的 TypeScript 支持。

🚨 避开一个常见误区

你可能在某些旧的或 Webpack 相关的资料中看到在 vite.config.ts 中配置 process.env 的做法：

typescript

// vite.config.ts
export default defineConfig({
  define: {
    'process.env': loadEnv(mode, process.cwd())
  },
})

这是不推荐且不必要的。Vite 使用的是 import.meta.env 而不是 process.env。正确的做法是直接使用 import.meta.env.VITE_XXX，并让 env.d.ts 文件为其提供类型支持。

💎 记住关键点

• env.d.ts 不执行，它只用于类型声明。

• 它的作用是开发时为 TypeScript 提供类型提示和检查。

• 真正在构建时被读取并注入变量值的是你的 .env 系列文件。

• 使用 import.meta.env 来访问客户端环境变量，并在 env.d.ts 中为其定义类型。