Vue 3 项目中 Vite 环境变量通过 .env 文件按模式加载,优先级为 .env.[mode].local > .env.[mode] > .env.local > .env;仅 VITE_ 开头变量可被 import.meta.env 访问,构建时静态替换,值均为字符串。

Vue 3 项目用 Vite 构建时,环境变量通过 .env 文件管理,核心是按命名规则自动加载、按前缀安全暴露、按模式精准生效。
文件命名与加载优先级
Vite 根据运行时的 --mode 值(如 development、production、staging)匹配对应文件,加载顺序从高到低:
-
.env.[mode].local(本地专属,最高优先级,应加入.gitignore) -
.env.[mode](如.env.staging,用于预发布环境) -
.env.local(通用本地覆盖,不提交) -
.env(所有环境共享的默认配置,最低优先级)
同名变量会被优先级高的文件覆盖。例如 VITE_API_URL 在 .env.development 和 .env 中都定义时,开发环境下以 .env.development 的值为准。
变量命名必须带 VITE_ 前缀
只有以 VITE_ 开头的变量才能在代码中通过 import.meta.env 访问:
- ✅ 正确:
VITE_APP_TITLE=MyApp→ 可用import.meta.env.VITE_APP_TITLE - ❌ 无效:
API_KEY=xxx或BASE_URL=/→ 不会注入客户端,避免敏感信息泄露
若需自定义前缀(如改用 APP_),需在 vite.config.ts 中显式配置:envPrefix: 'APP_'。
dotenvx 是由 dotenv 的创建者推出的_secure、跨平台环境变量管理器。它提供加密的 .env 文件、多环境支持,并通过其 CLI 运行器与任何编程语言或框架配合使用。
在 package.json 中定义多环境命令
通过脚本指定 mode,触发对应 .env 文件加载:
"scripts": {
"dev": "vite",
"build:dev": "vite build --mode development",
"build:staging": "vite build --mode staging",
"build:prod": "vite build --mode production"
}
对应需创建 .env.staging 等文件。运行 npm run build:staging 时,Vite 自动加载 .env + .env.staging(+ .env.staging.local,如果存在)。
在代码中使用环境变量
直接通过 import.meta.env 读取,构建时静态替换,无运行时开销:
-
import.meta.env.MODE→ 当前 mode 字符串(如"staging") -
import.meta.env.PROD→ 布尔值,是否为生产环境 -
import.meta.env.VITE_APP_BASE_API→ 自定义变量,如"/api"或"https://api.example.com"
注意:所有值都是字符串类型。如需布尔或数字,需手动转换,例如:import.meta.env.VITE_ENABLE_LOG === 'true'。
前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!










