Vite 环境配置指南

环境变量的基础概念

在 Vite 项目中，环境变量是一种在不同环境（开发、生产、测试等）之间切换配置的有效方式。Vite 提供了一套完整的环境变量解决方案。

环境变量命名规则

• 以 VITE_ 开头的变量会被暴露给客户端代码
• 其他变量仅在构建过程中可用

VITE_API_URL=http://api.example.com    // ✅ 客户端可访问
SECRET_KEY=123456                      // ❌ 客户端不可访问

import.meta 详解

什么是 import.meta

import.meta 是 ECMAScript 模块系统提供的特殊对象，用于访问模块的元信息。在 Vite 中，它被扩展用于访问环境变量。

常用属性

// 环境变量访问
console.log(import.meta.env.VITE_APP_TITLE)
 
// 模块 URL
console.log(import.meta.url)
 
// 内置环境变量
console.log(import.meta.env.MODE)    // 当前模式
console.log(import.meta.env.DEV)     // 是否开发环境
console.log(import.meta.env.PROD)    // 是否生产环境
console.log(import.meta.env.BASE_URL) // 基础公共路径

环境配置文件

文件命名规则

.env                # 所有环境
.env.local          # 所有环境（本地）
.env.development    # 开发环境
.env.production     # 生产环境
.env.test           # 测试环境

配置文件示例

# .env.development
VITE_API_URL=http://dev-api.example.com
VITE_APP_TITLE=开发环境
 
# .env.production
VITE_API_URL=http://api.example.com
VITE_APP_TITLE=生产环境

环境切换与命令

package.json 配置

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "dev:test": "vite --mode test",
    "build:test": "vite build --mode test"
  }
}

运行命令

yarn dev      # 开发环境
yarn build    # 生产环境
yarn dev:test # 测试环境

最佳实践与示例

配置文件管理

// config/index.js
const config = {
  development: {
    apiUrl: import.meta.env.VITE_API_URL,
    title: import.meta.env.VITE_APP_TITLE,
  },
  production: {
    apiUrl: import.meta.env.VITE_API_URL,
    title: import.meta.env.VITE_APP_TITLE,
  }
}
 
export default config[import.meta.env.MODE]

vite.config.js 配置

import { defineConfig } from 'vite'
 
export default defineConfig(({ command, mode }) => {
  return {
    base: mode === 'production' ? '/prod/' : '/',
    server: {
      port: mode === 'development' ? 3000 : 8080,
    },
    build: {
      // 生产环境配置
      rollupOptions: {
        // ...
      }
    }
  }
})

类型支持

环境变量类型声明

// env.d.ts
interface ImportMetaEnv {
  readonly VITE_APP_TITLE: string
  readonly VITE_API_URL: string
  // 更多环境变量...
}
 
interface ImportMeta {
  readonly env: ImportMetaEnv
}

注意事项与常见问题

1. 安全性考虑

   • 只有 VITE_ 前缀的变量会暴露给客户端
   • 敏感信息不要存储在客户端可访问的变量中

2. 构建优化

   • 环境变量在构建时被静态替换
   • 不要在运行时动态访问环境变量

3. 本地开发

   • 使用 .env.local 存放本地特定配置
   • .env.local 应该被加入 .gitignore

4. 最佳实践

   • 集中管理环境配置
   • 使用类型声明增强开发体验
   • 遵循环境变量命名规范

Vite 的环境配置系统提供了强大而灵活的功能，通过合理使用环境变量和配置文件，可以很好地管理不同环境下的应用行为。遵循最佳实践和注意事项，可以构建出更安全、可维护的应用。