loadEnv 不能在 vite.config.js 顶层同步调用，必须在 defineConfig 函数式配置中通过 Vite 注入的 mode 参数调用，以确保读取正确的 .env.[mode] 文件；仅 VITE_ 开头变量默认注入客户端，其余需通过 define 手动注入。
在 Vite 中，loadEnv 是专门用于读取 .env 文件中环境变量的工具函数，但它**不能直接在 vite.config.js 的顶层同步调用并期望拿到变量**——因为 Vite 配置文件执行时，Vite 还未确定运行模式（mode），而 loadEnv 需要 mode 才能决定加载哪个文件（如 .env.development 或 .env.production）。
loadEnv 必须配合 mode 使用
loadEnv(mode, root, prefix) 是 Vite 内置函数（无需安装），它会根据传入的 mode 去 root 目录下查找对应环境文件（如 .env.[mode]、.env），并返回一个包含变量的对象。但注意：
-
mode不是自动获取的，需显式指定（常见为'development'或'production'）； - Vite 启动时通过
--mode参数决定实际 mode（默认是development），但vite.config.js在启动初期就执行，此时还没解析命令行参数； - 因此，**不能在配置顶层直接写
loadEnv('development', ...)硬编码 mode**，否则构建或开发时可能读错文件。
正确方式：在 defineConfig 的函数式配置中使用 loadEnv
Vite 推荐把 vite.config.js 导出为一个函数，接收 { mode } 参数（Vite 会自动注入当前 mode），再在内部调用 loadEnv：
Json Schema Toolkit
下载
使用 JSON Schema 验证 JSON 数据，从示例 JSON 生成 schema，并将其转换为 TypeScript 接口、Python 数据类或 Markdown 文档。
import { defineConfig, loadEnv } from 'vite'
<p>export default defineConfig(({ mode }) => {
// ✅ 此时 mode 已由 Vite 解析好（如 'development' 或 'production'）
const env = loadEnv(mode, process.cwd(), '')</p><p>return {
define: {
<strong>APP_ENV__: JSON.stringify(env.APP_ENV),
</strong>API_BASE__: JSON.stringify(env.VUE_APP_API<em>BASE), // 注意：Vite 默认只暴露以 VITE</em> 开头的变量给客户端
},
// 其他配置...
}
})
这样就能确保读取的是当前命令实际使用的环境文件（例如运行 vite --mode staging 就会加载 .env.staging）。
VITE_ 前缀是关键：服务端可用 vs 客户端可见
Vite 对环境变量有明确约定：
- 只有以
VITE_开头的变量，才会被自动注入到客户端代码中（通过import.meta.env访问）； - 其他变量（如
API_BASE、DB_HOST）默认只在 Node 环境（如vite.config.js）中可用，不会暴露给浏览器； - 若想让非
VITE_变量也进客户端，必须手动通过define显式注入（如上例），且需自行处理字符串化和类型安全。
常见误区与建议
- ❌ 不要在顶层 import 后立刻调用
loadEnv—— mode 未知，读取结果不可靠； - ❌ 不要依赖
process.env.NODE_ENV判断 mode —— 它不等于 Vite 的mode（比如node_env=production但vite --mode test时 mode 是test）； - ✅ 推荐在
.env中设通用变量，在.env.[mode]中覆盖特定值； - ✅ 若只需客户端变量，优先用
import.meta.env.VITE_*，简单安全； - ✅ 如需服务端逻辑（如动态代理配置、插件参数），才在
defineConfig(() => {...})中用loadEnv。
