@quiteer/vite-plugins · envTypesPlugin

概述

扫描项目根目录下的 .env* 文件，自动生成 env.d.ts，为 import.meta.env 提供类型提示与补全。

安装与使用

import { defineConfig } from 'vite'
import { envTypesPlugin } from '@quiteer/vite-plugins'

export default defineConfig({
  plugins: [envTypesPlugin()]
})

选项

• root?: string：项目根目录，默认 Vite config.root
• envFilePatterns?: string[]：默认 ['.env', '.env.*', '.env.*.local', '.env.local']
• includePrefixes?: string[]：默认读取 Vite envPrefix 或 ['VITE_']
• outputFile?: string：输出路径，默认 <root>/env.d.ts
• literalUnions?: boolean：是否生成“联合字面量类型”，默认 true。开启后会跨所有匹配的 .env* 文件聚合每个键的值并去重，输出更精确的类型；若无可聚合值则回退为 string。

示例

envTypesPlugin({
  includePrefixes: ['VITE_', 'APP_'],
  outputFile: 'types/env.d.ts',
  literalUnions: true
})

行为说明

• dev 与 build 阶段均会生成；dev 下监听 .env* 变更自动更新。
• 仅保留前缀匹配的变量，避免将私密变量暴露到 import.meta.env。
• 联合字面量类型收集规则：
  • 从所有匹配的 .env* 文件中读取同名键的值，去重并排序；空值与空字符串会被忽略。
  • 若某键在所有文件中均未赋值或仅出现空值，则生成 string 类型。
  • 生成的类型不进行布尔/数字推断，避免运行时隐式转换导致的类型不一致。

示例输出（片段）

// env.d.ts
interface ImportMetaEnv {
  readonly VITE_DESC: '通用环境变量' | '开发环境变量' | '生产环境变量'
  readonly VITE_API_URL: '/api' | '/v1' | '/v2' | string // 示例：当值较多或存在非枚举值时，可能包含 string
}
interface ImportMeta { readonly env: ImportMetaEnv }

关闭联合字面量类型

• 如需保持所有键为 string，设置 literalUnions: false。