前端工程化 / 系统课时
加载环境变量
加载环境变量
本课完成一套可验证的环境变量读取方案:让 .env 中的端口和代理地址参与 Vite 配置,同时只把允许公开的 VITE_ 变量交给客户端代码,明确两条读取路径的边界。
学习目标
- 理解配置阶段变量与客户端变量的加载时机
- 使用
loadEnv按mode和前缀读取变量 - 正确处理字符串转换、优先级与敏感信息
环境变量的两条读取路径
Vite 在解析用户配置之后,才根据最终的 root、envDir 和 mode 加载 .env 文件。因此,vite.config.ts 执行时不会自动从这些文件获得 process.env.APP_PORT。配置本身需要变量时,应主动调用 loadEnv。
客户端是另一条路径:Vite 会把符合 envPrefix 的变量暴露为 import.meta.env,默认前缀是 VITE_。loadEnv 的第三个参数只决定配置函数读取哪些前缀,不会自动扩大客户端暴露范围。

准备模式文件
在项目根目录创建通用文件 .env:
VITE_APP_TITLE=Order Console
APP_PORT=5173
APP_API_ORIGIN=http://localhost:8080再创建 .env.staging,只覆盖预发布环境的差异:
VITE_APP_TITLE=Order Console Staging
APP_PORT=5174
APP_API_ORIGIN=https://staging-api.example.com执行 --mode staging 时,模式文件中的同名变量覆盖 .env。本地私有覆盖应写入 .env.local 或 .env.staging.local,并确保 *.local 不提交到仓库。
在配置阶段调用 loadEnv
下面的配置读取 APP_ 与 VITE_ 两类变量。APP_ 只服务于配置,VITE_ 既能被配置读取,也会按默认规则暴露给客户端。
import { defineConfig, loadEnv } from 'vite'
function toPort(value: string | undefined, fallback: number): number {
const port = Number(value)
return Number.isInteger(port) && port > 0 && port <= 65535
? port
: fallback
}
export default defineConfig(({ mode }) => {
const env = loadEnv(mode, process.cwd(), ['APP_', 'VITE_'])
const port = toPort(env.APP_PORT, 5173)
const apiOrigin = env.APP_API_ORIGIN || 'http://localhost:8080'
console.log(`[config] mode=${mode} port=${port} api=${apiOrigin}`)
return {
server: {
port,
strictPort: true,
proxy: {
'/api': {
target: apiOrigin,
changeOrigin: true,
},
},
},
}
})loadEnv 返回的值都是字符串,所以端口必须显式转换并校验。若项目设置了自定义 envDir,第二个参数也应指向同一目录,不能机械地使用 process.cwd()。运行预发布模式:
npm run dev -- --mode staging预期输出:
[config] mode=staging port=5174 api=https://staging-api.example.com实际启动日志还会包含本机访问地址,端口被占用且启用了 strictPort 时则会直接报错,而不是自动换端口。
验证客户端暴露范围
在任意由 Vite 处理的客户端模块中加入以下片段示例,用于检查默认前缀规则:
console.log(import.meta.env.VITE_APP_TITLE)
console.log(import.meta.env.APP_PORT)预期输出:
Order Console Staging
undefined第一项来自 VITE_ 前缀,会进入客户端;第二项虽然被配置阶段的 loadEnv 读取,但不符合默认客户端前缀,因此不会出现在 import.meta.env。不要把令牌、密码或私钥命名为 VITE_*,这些值会进入客户端代码。
优先级与常见问题
启动命令中已经存在的进程环境变量优先级最高,不会被 .env 文件覆盖;模式文件高于通用 .env。修改 .env 后需要重启开发服务器,热更新不会重新完成整个环境加载过程。
不要用 mode 代替 NODE_ENV。例如 vite build --mode staging 的模式是 staging,但它仍是生产构建。配置阶段应按业务环境读取 mode,按运行类型读取 command,两者各司其职。
当变量为 undefined 时,依次核对文件名、执行时的 --mode、loadEnv 的目录和前缀。即使为了配置需要使用 loadEnv(mode, envDir, '') 读取全部变量,也不要把返回对象整体注入 define 或客户端。