Vite环境变量配置

环境变量是前端项目配置的重要组成部分，它们帮助我们在不同环境中管理不同的配置值。

Vite环境变量配置

文件命名规则

Vite 使用特定的文件命名规则来区分不同环境：

复制代码

.env                # 所有环境加载
.env.local          # 所有环境加载，但被git忽略
.env.[mode]         # 只在指定模式加载（development-开发环境/production-生产环境）
.env.[mode].local   # 只在指定模式加载，但被git忽略

[mode]允许我们可以为不同环境定义不同的变量：

js 复制代码

# .env.development
VITE_API_BASE=http://localhost:3000/api
VITE_DEBUG=true

# .env.production  
VITE_API_BASE=https://api.example.com
VITE_DEBUG=false

使用不同模式：

bash 复制代码

# 开发模式（默认）
vite

# 生产模式
vite build --mode production

# 自定义模式
vite build --mode staging

环境变量加载优先级：

理解加载顺序很重要，后面的会覆盖前面的：

.env - 基础配置（最低优先级）
.env.local - 本地覆盖（不提交到 git）
.env.[mode] - 环境特定配置
.env.[mode].local - 环境特定本地覆盖

如果当前为生产环境时，.env和.env.production文件具有相同的变量，则.env.production文件拥有更高的优先级。

内置常量：

import.meta.env.MODE: 应用运行的模式。
import.meta.env.BASE_URL:部署应用时的基本 URL。由base 配置项决定。
import.meta.env.PROD : 应用是否运行在生产环境（使用 NODE_ENV='production' 运行开发服务器或构建应用时使用 NODE_ENV='production' ）。
import.meta.env.DEV : 应用是否运行在开发环境 (永远与 import.meta.env.PROD相反)。
import.meta.env.SSR: 应用是否运行在 server 上。

环境变量：

vite项目中的环境变量需要以VITE_为前缀。

Vite 自动将环境变量暴露在 import.meta.env 对象下，作为字符串。

js 复制代码

# .env
VITE_SOME_KEY=123
DB_PASSWORD=foobar

js 复制代码

console.log(import.meta.env.VITE_SOME_KEY) // "123"
console.log(import.meta.env.DB_PASSWORD) // undefined

如果你想要自定义环境变量的前缀，可以在vite.config.js中配置envPrefix选项。

自定义环境变量前缀：

envPrefix：

作用：是一个环境变量前缀过滤器，用于限制哪些环境变量会被应用程序读取和使用
类型： string | string[]
默认：VITE_

js 复制代码

// vite.config.js
export default defineConfig({
  envPrefix: 'APP_', // 使用特定前缀APP_，只有以 APP_ 开头的环境变量会暴露给客户端      
  // 其他配置...
})

以 envPrefix 开头的环境变量会通过 import.meta.env 暴露在你的客户端源码中。

安全注意事项：

envPrefix 不应被设置为空字符串 ''，这将暴露你所有的环境变量，导致敏感信息的意外泄漏。检测到配置为 '' 时 Vite 将会抛出错误。
- 假设你的系统有以下环境变量：
  .env 复制代码
```
DATABASE_PASSWORD=secret123
API_KEY=abc123def456
AWS_ACCESS_KEY=AKIA...
AWS_SECRET_KEY=...
PATH=/usr/bin:/bin
HOME=/home/user
```
- 当 envPrefix = 'APP_' 时：只读取以 APP_ 开头的变量，其他敏感变量被忽略，是安全的；
- 当 envPrefix = '' 时：读取所有环境变量，包括数据库密码、API密钥等敏感信息，有安全风险；
如果你想暴露一个不含前缀的变量，可以使用 define 选项：

define:

可以通过 define 选项来显式暴露环境变量，即使这些变量没有 envPrefix 要求的前缀。

js 复制代码

// vite.config.js
export default defineConfig({
  envPrefix: 'VITE_', // 仍然保持安全过滤
  
  define: {
    // 显式暴露不含 VITE_ 前缀的变量
    'import.meta.env.API_URL': JSON.stringify(process.env.API_URL),
    'import.meta.env.APP_VERSION': JSON.stringify(process.env.APP_VERSION),
    
    // 或者定义常量值
    '__APP_NAME__': JSON.stringify('我的应用'),
  },
})

js 复制代码

// 通过 envPrefix 暴露的变量
console.log(import.meta.env.VITE_API_BASE)

// 通过 define 暴露的变量  
console.log(import.meta.env.API_URL)
console.log(import.meta.env.APP_VERSION)

// 通过 define 定义的常量
console.log(__APP_NAME__)

注意事项：

安全性：define 会直接将值编译到代码中，确保不要暴露敏感信息；
字符串化：必须使用 JSON.stringify() 包装值；

构建时确定：每项在开发环境下会被定义在全局，而在构建时被静态替换，运行时无法更改；

配置：

js 复制代码

// vite.config.js
export default defineConfig({
  define: {
    '__APP_NAME__': JSON.stringify('我的应用'),
    '__VERSION__': JSON.stringify('1.2.3'),
    'import.meta.env.MODE': JSON.stringify(process.env.NODE_ENV),
    'globalThis.IS_DEV': process.env.NODE_ENV === 'development',
  }
})

源代码：

js 复制代码

// src/main.js
console.log('应用名称:', __APP_NAME__)
console.log('版本:', __VERSION__)
console.log('模式:', import.meta.env.MODE)
if (globalThis.IS_DEV) {
  console.log('这是开发环境')
}

构建后：

js 复制代码

// dist/assets/index-xxxx.js
console.log('应用名称:', "我的应用")  // 直接替换
console.log('版本:', "1.2.3")        // 直接替换  
console.log('模式:', "development")  // 直接替换
if (false) {                        // 直接替换为布尔值
  console.log('这是开发环境')        // 这行代码会被 tree-shaking 移除
}

`webpack`和`vite`配置环境变量的区别：

特性	Webpack (Vue CLI)	Vite
构建理念	打包时编译	按需编译
配置方式	`vue.config.js`	`vite.config.js`
环境变量前缀	`VUE_APP_`	`VITE_`
访问方式	`process.env`	`import.meta.env`
加载方式	自动加载	使用 `loadEnv()` 函数
配置导出	CommonJS	ES Module
热更新	需要重启	支持热更新

迁移建议

从 Webpack 迁移到 Vite 时：

重命名环境变量 : VUE_APP_* → VITE_*
更新访问方式 : process.env → import.meta.env
修改配置文件 : vue.config.js → vite.config.js
更新类型定义: 环境变量类型声明文件
测试验证: 确保所有环境变量在不同环境下正常工作

Vite环境变量配置