前端开发之环境配置

一、 Vite 环境文件加载优先级解析

Vite 的环境变量文件加载遵循特定优先级规则，确保开发环境配置的灵活性和安全性。以下是文件加载顺序及典型应用场景：

环境文件优先级顺序

.env.development.local > .env.development > .env.local > .env

.env.development.local

优先级最高，专用于开发环境且仅本地有效。不会被 Git 跟踪，适合存放开发者个人调试配置或敏感信息（如本地数据库密码）。
.env.development

团队共享的开发环境配置，提交到版本控制。包含公共开发配置（如 API 基础路径），但避免敏感信息。
.env.local

全局本地覆盖文件，适用于所有环境（开发/生产）。通常用于临时覆盖生产环境变量进行本地测试。
.env

基础配置文件，提供默认值。根据当前模式（development/production）自动匹配对应环境变量。

实际应用场景示例

团队协作配置管理

公共开发配置（如 mock API 开关）写入 .env.development，提交至代码库
个人本地代理设置或测试账号写入 .env.development.local，添加到 .gitignore

敏感信息防护

生产环境密钥应通过 .env.production.local 或部署平台的环境变量注入，避免直接提交配置文件。

技术实现原理

Vite 使用 dotenv 扩展库加载文件，优先级高的文件后加载，通过 Object.assign 合并变量。仅 VITE_ 前缀的变量会暴露给客户端代码：

javascript 复制代码

// 伪代码逻辑示意
const env = {
  ...load('.env'),
  ...load('.env.local'),
  ...load('.env.development'),
  ...load('.env.development.local')
}

注意事项

修改环境文件后需重启开发服务器
生产环境构建时只加载 .env.production 和 .env.production.local
客户端可通过 import.meta.env.VITE_XXX 访问暴露的变量

二、Vite 环境变量类型声明解析

三斜线指令与基础类型引入

typescript 复制代码

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

该指令引入Vite客户端类型定义，包含：

import.meta.env基础结构
import.meta.hot热更新API
静态资源导入类型（如.svg/.png等）

自定义环境变量类型定义

typescript 复制代码

interface ImportMetaEnv {
  readonly VITE_ENV: 'development' | 'staging' | 'production'
  readonly VITE_API_URL: string
  readonly VITE_SSO_ENABLED: string
  readonly VITE_LOG_LEVEL: 'debug' | 'info' | 'warn' | 'error'
  readonly VITE_FEATURE_DEBUG_PANEL: string
  readonly VITE_FEATURE_ANALYTICS: string
  readonly VITE_FEATURE_EXPERIMENTAL: string
}

字段特性说明

VITE_ENV：限定三种环境标识的联合类型
VITE_SSO_ENABLED：存储为字符串（因.env文件限制）
VITE_LOG_LEVEL：限定四种日志级别
readonly修饰符：防止运行时修改

类型扩展实现

typescript 复制代码

interface ImportMeta {
  readonly env: ImportMetaEnv
}

通过扩展全局import.meta接口，使.env属性使用自定义类型。

环境变量处理实践

字符串转布尔值

typescript 复制代码

function parseBoolean(value: string | undefined): boolean {
  return value === 'true'
}

因.env文件值均为字符串，需显式转换布尔型变量。

类型声明优势对比

场景	无声明文件	有声明文件
代码提示	无	显示完整变量选项
拼写错误	静默通过	编译报错
非法赋值	允许	类型检查拦截
悬停查看类型	显示any	显示具体类型

文件存放位置

建议置于src/目录下，确保被tsconfig.json的include规则覆盖，使TypeScript能自动识别类型声明。文件名为vite-env.d.ts

三、vite-env.d.ts 与 env.ts 的核心区别

文件性质差异

vite-env.d.ts 是纯类型声明文件（.d.ts），仅用于 TypeScript 类型检查和 IDE 提示，编译后不会生成实际代码。
env.ts 是常规 TypeScript 文件（.ts），包含可执行逻辑，编译后会保留为运行时代码。

功能定位对比

vite-env.d.ts 通过扩展 ImportMetaEnv 接口声明环境变量的存在性和类型，例如：
typescript 复制代码
```
interface ImportMetaEnv {
  readonly VITE_API_URL: string
}
```

env.ts 负责环境变量的加工和封装，提供统一访问入口，例如：

typescript 复制代码

export const env = {
  apiUrl: import.meta.env.VITE_API_URL,
  isProd: import.meta.env.MODE === 'production'
}

典型使用场景

直接使用 import.meta.env 时需依赖 vite-env.d.ts 获得类型提示，但需手动处理原始类型（如字符串转布尔值）。
通过 env.ts 导出的对象可直接使用处理后的值（如布尔值、计算属性），避免业务层重复转换逻辑。

工作流关系

.env 文件定义原始环境变量（如 VITE_FEATURE_FLAG=true）。
vite-env.d.ts 声明这些变量的类型（如 VITE_FEATURE_FLAG: string）。
env.ts 解析并转换值（如将 "true" 转为 boolean），最终暴露结构化对象。

选择建议

需要严格的类型检查或避免拼写错误时，必须配置 vite-env.d.ts。
需要统一管理环境变量或提供便捷方法（如 isDev）时，应使用 env.ts。两者通常配合使用。