Vite 环境变量的类型安全契约：用 import.meta.env 泛型与 zod 校验终结 undefined 地狱

环境变量是前端项目里最容易被忽视的一层契约：它既不像组件 Props 那样有类型推导，也不像接口返回那样有 Schema 约束，往往只是一个裸的 string | undefined。于是生产环境里最经典的翻车场景便层出不穷——某个新环境变量没配，运行时访问它返回 undefined，却在某个深层逻辑里被当作字符串拼进了 URL。

本文要解决的问题很明确：如何让环境变量像组件的 Props 一样，同时具备编译期类型约束与运行期校验。答案落在 Vite 提供的 import.meta.env 类型增强机制，以及 zod 这类轻量校验库的配合上。

先看清问题：import.meta.env 的默认类型有多弱

Vite 会把以 VITE_ 开头的变量注入到 import.meta.env 里，但它的类型默认是 any 或一条宽泛的记录。当你写下下面这行，编译器不会给你任何帮助：

// 没有类型增强时，这是 any，拼错也不会报错
const apiUrl = import.meta.env.VITE_API_URL;
// 编译通过，运行时拿到 undefined，最终拼出一个 /undefined/... 的 URL
fetch(`${apiUrl}/users`);

反面案例就是这种「编译静默通过、运行静默出错」的陷阱。很多团队为了省事，干脆在 vite-env.d.ts 里顺手写一个 interface ImportMetaEnv { [key: string]: any }，看似一劳永逸，实则把类型系统的最后一层防线也拆掉了。

第一步：用一个精确的接口替换 any

Vite 官方约定的做法，是在 src/vite-env.d.ts 里扩展 ImportMetaEnv 接口。关键在于——字段要声明为明确类型，而不是 any：

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

interface ImportMetaEnv {
  readonly VITE_API_URL: string;
  readonly VITE_APP_TITLE: string;
  readonly VITE_ENABLE_MOCK: 'true' | 'false';
  readonly VITE_MAX_RETRY: string; // 注意：env 里永远是字符串
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

这样声明后，前面那段代码的行为立刻反转：拼错变量名会直接报错，类型也从一个笼统的 any 收窄成了具体的 string。但这只是编译期的「信任」，它默认你部署时真的配了这些变量。

一个容易被忽略的细节：环境变量的值永远是字符串。所以 VITE_ENABLE_MOCK 即便表示布尔语义，类型也只能写 'true' | 'false' 字面量联合，而不是 boolean。这恰恰是很多人写 env 类型时踩的坑——给 VITE_MAX_RETRY 标了 number，运行时拿到的却是 "3"，"3" + 1 变成了 "31"。

第二步：用 zod 把「信任」升级成「校验」

类型声明只能保证编译期不写错，却拦不住部署时漏配变量。真正的防线是运行期校验。这里引入 zod，在应用启动时对 import.meta.env 做一次完整的解析：

import { z } from 'zod';

const envSchema = z.object({
  VITE_API_URL: z.string().url(),
  VITE_APP_TITLE: z.string().min(1),
  VITE_ENABLE_MOCK: z.enum(['true', 'false']).transform(v => v === 'true'),
  VITE_MAX_RETRY: z.coerce.number().int().min(1).max(10),
});

const parsed = envSchema.safeParse(import.meta.env);

if (!parsed.success) {
  // 启动即失败，把缺失的变量名直接打印出来，而不是让错误潜伏到运行时
  console.error('环境变量缺失或非法：', parsed.error.flatten().fieldErrors);
  throw new Error('环境变量校验失败');
}

export const env = parsed.data;

对比一下正反两面的差异：

反面：全项目散落着 import.meta.env.VITE_API_URL，某天后端改了域名没同步前端配置，报错点出现在距离启动十万八千里的一个组件里，排查半天只能靠 grep。

正面：所有环境变量在 main.ts 入口一次性校验，缺失、格式错误当场抛出，错误信息精确到字段名。env.VITE_MAX_RETRY 拿到的是真正的 number，可以直接参与运算。

第三步：让编译期类型与运行期校验保持同步

zod 的一个附带福利是，它可以从 Schema 反向推导出 TypeScript 类型，从而避免「手写 interface」和「实际校验规则」两处漂移。方向有两种，你可以只保留其中一处作为唯一事实来源：

// 只保留 schema，用 z.infer 推导类型
const envSchema = z.object({
  VITE_API_URL: z.string().url(),
  VITE_APP_TITLE: z.string(),
});
type Env = z.infer<typeof envSchema>;

// 或者：保留精确的 interface，让 schema 去 satisfy 它，防止两处不一致
interface Env {
  readonly VITE_API_URL: string;
  readonly VITE_APP_TITLE: string;
}
const envSchema = z.object({
  VITE_API_URL: z.string().url(),
  VITE_APP_TITLE: z.string(),
}) satisfies z.ZodType<Env>;

z.infer 派生的类型可以直接注入到全局，替换掉 vite-env.d.ts 里手写的那份。如此一来，import.meta.env 的类型声明、启动期校验、业务代码里的消费类型，三者由同一个 Schema 驱动，从根源上消灭了「改了类型忘了改校验」的漂移。

收尾：一个完整的落地清单

把上面的思路串起来，一个可交付的环境变量治理方案包含四件事：

1. 用 vite-env.d.ts 精确声明 ImportMetaEnv，字段类型不再是 any；
2. 针对布尔/数字等语义，在类型层用字面量联合标注「值永远是字符串」这一事实；
3. 用 zod 在入口对 import.meta.env 做 safeParse，失败即抛错，错误信息定位到字段；
4. 用 z.infer 让运行时 Schema 成为类型与校验的唯一事实来源。

环境变量本质上是一份「部署契约」，它跨越了前端、CI、运维三个环节。把这份契约像对待组件 API 一样精心设计，undefined 地狱自然不复存在。