Vite环境变量4个暗坑：1.5万开发者踩过的类型陷阱|代码|字符串|插件|暗坑|电子表格|陷阱

2023年Stack Overflow调研显示，67%的前端事故源于配置错误。Vite（一种前端构建工具）用户最头疼的，是把`"true"`当布尔值用了三个月才发现。

这是Vite环境变量的真实面貌：

```
import.meta.env.VITE_PORT // "5173" — 字符串，不是数字
import.meta.env.VITE_DARK // "true" — 字符串，不是布尔值
import.meta.env.VITE_API_URL // string | undefined — 零校验
```

所有值都是裸字符串。没有校验，没有服务端/客户端边界，没有泄漏检测。想要类型？手写`vite-env.d.ts`，自己维护。

暗坑一：万物皆字符串

你被迫手动强制转换。漏写`Number()`，或者对字符串用`=== true`，这种静默bug能通过所有检查，直到生产环境炸掉。

更隐蔽的是类型漂移。同事上周加了`VITE_FEATURE_FLAG`，忘了更新`vite-env.d.ts`。变量在`.env`里活得好好的，TypeScript一声不吭。

配置文件的谎言：你以为有类型保护，实际只是份没人看的文档。

暗坑二：服务端/客户端边界形同虚设

Vite的约定是：带`VITE_`前缀的变量进客户端，其他留服务端。没有强制执行，没有显式分割，越界了也不警告。

```
// shared/config.ts — 同时被服务端和客户端引入
export const db = process.env.DATABASE_URL // 静默打包进客户端
```

服务端和客户端代码共享模块时，机密跟着走。Bundler（打包工具）会内联值。Tree-shaking（树摇优化）和压缩后，服务端密钥的字面量可能直接嵌在客户端代码块里——没有引用痕迹，就是裸值躺在编译输出里。

暗坑三：泄漏检测为零

现有工具各管一段。`@t3-oss/env-core`在构建时校验，用Standard Schema（Zod、Valibot、ArkType）注入值，零运行时开销。但它不分割服务端/客户端变量，不提供虚拟模块，也不检测泄漏。

`@dotenvx/dotenvx`在导入时校验，用Proxy（代理对象）做运行时服务端/客户端保护，支持Vercel、Railway、Netlify等平台预设。代价是每个变量要列两遍，没有构建时泄漏检测，且与框架无关——无法hook进Vite的构建管道。

两个都是好工具。但Vite的四坑，它们都没填完。

新插件的解法：从约定到强制

开发者Anthony Fu（Vue、Vite核心团队成员）写了`@vite-env/core`。思路很直接：一个`env.ts`文件，插件包办校验、虚拟模块、类型生成、泄漏检测。

```
import { defineEnv } from '@vite-env/core'

export const env = defineEnv({
JWT_SECRET: z.string().min(32), // 服务端专属
DB_POOL_SIZE: z.coerce.number().int().default(10),
VITE_APP_NAME: z.string().min(1), // 客户端可见
VITE_DEBUG: z.stringbool().default(false),
VITE_LOG_LEVEL: z.enum(['debug','info','warn','error']).default('info'),
})
```

构建启动时跑校验。缺失或格式错误直接报错，不是运行时才暴露。

关键设计在边界处理。`JWT_SECRET`没`VITE_`前缀，插件确保它只在服务端虚拟模块可用。客户端代码试图导入？编译阶段拦截，不是运行时抛错。

泄漏检测靠静态分析。插件扫描构建产物，匹配服务端变量值，发现嵌入客户端就中断构建。

类型生成是副作用。`env.ts`即唯一信源，Zod schema（模式定义）同时驱动运行时校验和TypeScript声明，不再漂移。