Vite环境变量安装

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

Vite环境变量配置

文件命名规则

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

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

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

# .env.development
VITE_API_BASE=http://localhost:3000/api
VITE_DEBUG=true
# .env.production
VITE_API_BASE=https://api.example.com
VITE_DEBUG=false

使用不同模式：

# 开发模式（默认）
vite
# 生产模式
vite build --mode production
# 自定义模式
vite build --mode staging

环境变量加载优先级：

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

  1. .env - 基础配置（最低优先级）
  2. .env.local - 本地覆盖（不提交到 git）
  3. .env.[mode] - 环境特定配置
  4. .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 对象下，作为字符串。

# .env
VITE_SOME_KEY=123
DB_PASSWORD=foobar
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_

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

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

安全注意事项：

  • envPrefix 不应被设置为空字符串 ''，这将暴露你所有的环境变量，导致敏感信息的意外泄漏。 检测到配置为 '' 时 Vite 将会抛出错误。

    • 假设你的系统有以下环境变量：

      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 要求的前缀。

// 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('我的应用'),
},
})
// 通过 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() 包装值；

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

    • 配置：

      // 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',
}
})

    • 源代码：

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

    • 构建后：

      // 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.jsvite.config.js
环境变量前缀VUE_APP_VITE_
访问方式process.envimport.meta.env
加载方式自动加载使用 loadEnv() 函数
配置导出CommonJSES Module
热更新需要重启支持热更新

迁移建议

从 Webpack 迁移到 Vite 时：

  1. 重命名环境变量: VUE_APP_* → VITE_*
  2. 更新访问方式: process.env → import.meta.env
  3. 修改配置文件: vue.config.js → vite.config.js
  4. 更新类型定义: 环境变量类型声明文件
  5. 测试验证: 确保所有环境变量在不同环境下正常工作
posted @ 2025-12-23 18:31  clnchanpin  阅读(49)  评论(0)    收藏  举报