环境变量与多环境发布
约 484 字大约 2 分钟
2026-02-25
Vite 的环境变量体系核心是“按模式加载 + 前缀暴露控制”。这套机制解决了多环境配置混乱和敏感信息误暴露的问题。
环境文件加载规则
Vite 会按 mode 读取对应 .env 文件并合并。常见文件组织如下：
| 文件 | 作用 | 是否建议提交 |
|---|---|---|
.env | 所有模式共享配置 | 是 |
.env.local | 本机私有配置 | 否 |
.env.development | 开发环境配置 | 是 |
.env.production | 生产环境配置 | 是 |
.env.[mode].local | 特定模式下本机私有配置 | 否 |
暴露规则：只有 VITE_ 前缀可进客户端
这是最重要的安全边界。
# .env.production
VITE_API_BASE=https://api.example.com
VITE_APP_TITLE=My Console
SECRET_KEY=server-only-key// 客户端代码可访问
console.log(import.meta.env.VITE_API_BASE)
// 这里拿不到 SECRET_KEY
console.log(import.meta.env.SECRET_KEY) // undefined在代码中使用环境变量
if (import.meta.env.DEV) {
console.log('development mode')
}
if (import.meta.env.PROD) {
console.log('production mode')
}
const apiBase = import.meta.env.VITE_API_BASE在配置文件中按 mode 读取
当你需要在 vite.config.ts 里根据 mode 控制代理、base、构建行为时，用 loadEnv。
import { defineConfig, loadEnv } from 'vite'
export default defineConfig(({ mode }) => {
const env = loadEnv(mode, process.cwd(), '')
return {
base: env.VITE_PUBLIC_BASE || '/',
server: {
proxy: {
'/api': {
target: env.VITE_API_BASE,
changeOrigin: true,
},
},
},
}
})多环境发布脚本
package.json
{
"scripts": {
"dev": "vite",
"build:dev": "vite build --mode development",
"build:test": "vite build --mode test",
"build:prod": "vite build --mode production",
"preview": "vite preview"
}
}CI 示例
pnpm install --frozen-lockfile
pnpm run build:prod发布建议
- 先定义好环境变量命名规范（前缀、语义、归属）。
- 把敏感信息留在服务端，不通过
VITE_暴露。 - 每个 mode 对应独立发布流水线，避免“环境串线”。
- 通过
preview或灰度环境先验收构建产物。
常见误区
- 把密钥类变量加上
VITE_前缀直接暴露到客户端。 - 只在
.env写一份配置，导致多环境发布混用。 - 在配置文件中直接用
process.env，忽略 mode 维度差异。