vite --mode dev 环境变量未生效？

Question

在使用 Vite 构建项目时，开发者常通过 `vite --mode dev` 指定环境模式，期望加载 `.env.development` 等对应环境变量文件。然而，部分用户反馈执行该命令后，环境变量仍未生效，导致请求地址、功能开关等配置仍指向默认或生产环境。问题根源通常在于：Vite 仅识别以 `VITE_` 开头的变量，或 `.env` 文件命名不规范（如误用 `.env.dev` 而非 `.env.development`），亦或是缓存未清除导致旧配置残留。此外，自定义 mode 名称需配套创建对应环境文件（如 `.env.dev` 需显式存在并启用 `--mode dev`）。常见误解是认为 `--mode dev` 会自动加载所有 dev 相关变量，而忽视了 Vite 的环境文件加载规则和变量前缀限制，从而导致配置失效。

Answer 1

1. Vite 环境变量机制基础解析

在使用 Vite 构建前端项目时，环境变量的加载遵循一套明确的规则。开发者通过命令如 vite --mode dev 指定运行模式，期望加载对应的 .env.development 文件中的配置。然而，Vite 并不会自动识别所有变量，只有以 VITE_ 开头的变量才会被暴露到 import.meta.env 中。

例如：

# .env.development
VITE_API_URL=https://dev-api.example.com
DEBUG_MODE=true

在此例中，DEBUG_MODE 不会被注入到客户端代码中，因为它未以 VITE_ 开头。这是许多开发者首次遇到“环境变量未生效”问题的根本原因。

2. 环境文件命名规范与加载优先级

Vite 根据 --mode 参数决定加载哪个环境文件。其默认行为如下：

• .env：所有情况下都会加载
• .env.local：本地覆盖，不建议提交至版本控制
• .env.[mode]：仅在指定 mode 下加载（如 .env.development）
• .env.[mode].local：特定 mode 的本地覆盖

常见错误是创建了 .env.dev 而非 .env.development，而 Vite 默认将 development 作为开发模式名称，因此无法匹配该文件。

3. 自定义 Mode 与环境文件映射关系

当使用自定义 mode，如 vite --mode dev，必须确保存在对应的 .env.dev 文件，否则 Vite 将回退到默认配置。这要求开发者显式创建并维护这些文件。

示例结构：

Mode	应存在的文件	是否内置支持
development	.env.development	是
production	.env.production	是
staging	.env.staging	否（需手动创建）
dev	.env.dev	否（需手动创建）

4. 缓存与构建残留问题分析

Vite 在开发服务器启动时会缓存环境变量解析结果。若修改了 .env 文件但未重启服务，可能导致旧值持续生效。此外，构建产物中可能残留上一次构建的环境配置。

解决方案包括：

1. 每次修改环境文件后重启 Vite 服务
2. 清理 node_modules/.vite 缓存目录
3. 使用 vite build --mode production 显式指定模式避免歧义
4. 检查 CI/CD 流水线中是否正确传递了 --mode 参数

5. 深层排查流程图与诊断路径

为系统化定位环境变量失效问题，可参考以下 Mermaid 流程图进行逐层排查：

graph TD
    A[执行 vite --mode dev] --> B{是否存在 .env.dev?}
    B -->|否| C[检查是否误用 .env.dev 而非 .env.development]
    B -->|是| D{变量是否以 VITE_ 开头?}
    D -->|否| E[变量不会注入客户端]
    D -->|是| F[检查 import.meta.env 是否正确引用]
    F --> G{仍无效？}
    G --> H[清除 .vite 缓存并重启]
    H --> I[确认终端输出的 resolved config 中 envMode 是否为 dev]
    I --> J[验证最终行为]

6. 实际项目中的最佳实践建议

为避免上述问题反复出现，建议团队制定统一的环境管理规范：

• 统一使用标准 mode 名称：development, production, staging
• 禁止在非 VITE_ 前缀下暴露敏感或运行时配置
• 在 vite.config.js 中打印当前 mode 和加载的 env 文件路径用于调试
• 利用 define 配置项手动注入非 VITE_ 变量（谨慎使用）
• 在 CI 环境中通过脚本动态生成 .env 文件
• 结合 dotenv 加载库处理服务端逻辑所需的完整变量集
• 使用 TypeScript 定义 import.meta.env 类型增强安全性
• 建立自动化检测脚本验证构建前环境变量完整性
• 文档化各环境对应的 API 地址、功能开关等关键配置
• 定期审计 .env* 文件权限与泄露风险