环境变量与模式管理
项目配置与基础使用
Vite.js 的配置文件 vite.config.js 位于项目根目录，通过导出一个配置对象来定制构建行为。基本配置结构如下：
// vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
export default defineConfig({
plugins: [vue()],
server: {
port: 3000,
open: true
},
build: {
outDir: 'dist'
}
})
配置项主要分为几大类：
plugins: 配置需要使用的插件server: 开发服务器选项build: 生产构建选项resolve: 模块解析选项css: CSS 相关配置
常用配置示例：
// 更完整的配置示例
export default defineConfig({
base: '/my-app/', // 部署基础路径
publicDir: 'public', // 静态资源目录
resolve: {
alias: {
'@': path.resolve(__dirname, './src')
}
},
css: {
preprocessorOptions: {
scss: {
additionalData: `@import "@/styles/variables.scss";`
}
}
}
})
环境变量与模式管理
Vite 使用 dotenv 从项目根目录中的 .env 文件加载环境变量。环境变量文件命名规则：
.env: 所有情况下都会加载.env.local: 本地覆盖，会被 git 忽略.env.[mode]: 只在指定模式下加载.env.[mode].local: 指定模式的本地覆盖
基本使用方式：
# .env.development
VITE_API_URL=https://dev.api.example.com
VITE_DEBUG=true
# .env.production
VITE_API_URL=https://api.example.com
VITE_DEBUG=false
在代码中访问环境变量：
console.log(import.meta.env.VITE_API_URL)
模式是 Vite 的一个重要概念，默认有三种模式：
development: 用于vite或vite devproduction: 用于vite buildtest: 用于vite test
可以通过 --mode 选项指定自定义模式：
vite build --mode staging
对应需要创建 .env.staging 文件：
# .env.staging
VITE_API_URL=https://staging.api.example.com
高级环境变量配置
对于更复杂的环境变量需求，可以在 vite.config.js 中动态配置：
export default defineConfig(({ command, mode }) => {
// 根据当前命令(command)和模式(mode)加载不同的环境变量
const env = loadEnv(mode, process.cwd(), '')
return {
define: {
__APP_VERSION__: JSON.stringify(env.VITE_APP_VERSION || '1.0.0')
},
// 其他配置...
}
})
类型安全的环境变量可以通过在 src 目录下创建 env.d.ts 文件：
// src/env.d.ts
interface ImportMetaEnv {
readonly VITE_API_URL: string
readonly VITE_APP_TITLE: string
// 更多环境变量...
}
interface ImportMeta {
readonly env: ImportMetaEnv
}
多环境配置实践
大型项目通常需要管理多个环境配置。一个实用的组织方式：
├── config/
│ ├── env.development
│ ├── env.staging
│ ├── env.production
│ └── env.test
├── scripts/
│ └── build.js
└── vite.config.js
自定义构建脚本示例：
// scripts/build.js
const fs = require('fs')
const { execSync } = require('child_process')
const env = process.argv[2] || 'production'
const envFile = `./config/env.${env}`
if (!fs.existsSync(envFile)) {
console.error(`环境配置文件不存在: ${envFile}`)
process.exit(1)
}
// 复制环境文件到项目根目录
fs.copyFileSync(envFile, '.env')
console.log(`使用 ${env} 环境配置构建...`)
execSync('vite build', { stdio: 'inherit' })
使用方式：
node scripts/build.js staging
环境变量在 HTML 中的使用
Vite 支持在 index.html 中使用环境变量：
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>%VITE_APP_TITLE%</title>
</head>
<body>
<div id="app"></div>
<script>
console.log('当前环境:', '%MODE%')
</script>
</body>
</html>
需要在配置中启用 HTML 变量替换：
export default defineConfig({
// ...
html: {
inject: {
injectData: {
MODE: process.env.NODE_ENV,
VITE_APP_TITLE: process.env.VITE_APP_TITLE
}
}
}
})
跨项目环境变量共享
对于微前端架构或需要共享配置的场景，可以创建共享环境变量模块：
// shared-config/env.js
const sharedEnv = {
VITE_COMMON_API: 'https://common.api.example.com',
VITE_AUTH_DOMAIN: 'auth.example.com'
}
module.exports = {
development: {
...sharedEnv,
VITE_DEBUG: true
},
production: {
...sharedEnv,
VITE_DEBUG: false
}
}
在 Vite 配置中使用：
const sharedEnv = require('./shared-config/env.js')
export default defineConfig(({ mode }) => ({
define: {
'process.env': {
...sharedEnv[mode],
...process.env
}
}
}))
安全注意事项
环境变量处理需要注意的安全问题：
- 永远不要将敏感信息提交到版本控制
.env.local和*.local文件应该加入.gitignore- 客户端可见的变量必须以
VITE_开头 - 服务端专用变量应使用其他前缀并通过后端注入
# 不安全的做法 - 这些变量会被包含在客户端代码中
API_KEY=123456
DB_PASSWORD=secret
# 安全的做法 - 只有 VITE_ 前缀的变量会暴露给客户端
VITE_PUBLIC_KEY=pub_123
VITE_API_URL=/api
测试环境特殊处理
测试环境通常需要特殊配置：
// vite.config.js
export default defineConfig(({ mode }) => {
const isTest = mode === 'test'
return {
test: {
environment: 'jsdom',
globals: true,
setupFiles: './tests/setup.js',
// 测试专用的环境变量
env: {
VITE_TEST_MODE: 'true',
VITE_MOCK_API: 'true'
}
},
// 其他配置...
}
})
测试文件中使用环境变量：
// tests/example.spec.js
import { describe, it, expect } from 'vitest'
describe('环境变量测试', () => {
it('应该在测试模式下', () => {
expect(import.meta.env.VITE_TEST_MODE).toBe('true')
})
})
环境变量验证
可以使用 zod 等库对环境变量进行验证：
// src/utils/env.ts
import { z } from 'zod'
const envSchema = z.object({
VITE_API_URL: z.string().url(),
VITE_ENABLE_ANALYTICS: z.boolean().default(false),
VITE_TIMEOUT: z.number().default(5000)
})
const env = envSchema.parse({
VITE_API_URL: import.meta.env.VITE_API_URL,
VITE_ENABLE_ANALYTICS: import.meta.env.VITE_ENABLE_ANALYTICS === 'true',
VITE_TIMEOUT: Number(import.meta.env.VITE_TIMEOUT)
})
export default env
动态配置加载
对于需要根据环境动态加载配置的场景：
// src/config/index.js
const env = import.meta.env.MODE
const configs = {
development: {
apiBase: 'https://dev.api.example.com',
analyticsId: 'UA-DEV-123'
},
production: {
apiBase: 'https://api.example.com',
analyticsId: 'UA-PROD-456'
},
test: {
apiBase: 'http://localhost:3000/mock',
analyticsId: null
}
}
export default configs[env] || configs.development
构建产物中的环境信息
将环境信息注入到构建产物中：
export default defineConfig({
build: {
rollupOptions: {
output: {
banner: `/*!
* App Version: ${process.env.npm_package_version}
* Build Date: ${new Date().toISOString()}
* Environment: ${process.env.NODE_ENV}
*/`
}
}
}
})
环境相关的资源处理
根据环境加载不同的资源：
// 动态加载环境相关的图片
function getEnvImage(name) {
const env = import.meta.env.MODE
return new URL(`../assets/${env}/${name}.png`, import.meta.url).href
}
// 使用
const logo = getEnvImage('logo')
环境特定的插件配置
某些插件可能需要根据环境进行不同配置：
import { visualizer } from 'rollup-plugin-visualizer'
export default defineConfig(({ mode }) => {
const plugins = []
if (mode === 'production') {
plugins.push(
visualizer({
open: true,
filename: 'bundle-analysis.html'
})
)
}
return {
plugins
}
})
环境变量与代理配置
开发环境常用的代理配置：
export default defineConfig({
server: {
proxy: {
'/api': {
target: import.meta.env.VITE_API_BASE || 'http://localhost:8080',
changeOrigin: true,
rewrite: path => path.replace(/^\/api/, '')
}
}
}
})
环境相关的 CSS 处理
根据环境注入不同的 CSS 变量：
export default defineConfig({
css: {
postcss: {
plugins: [
require('postcss-preset-env')({
stage: 3,
features: {
'nesting-rules': true
},
// 环境相关的 CSS 变量
variables: {
'--env-color':
import.meta.env.MODE === 'production'
? '#1a1a1a'
: '#4a90e2'
}
})
]
}
}
})
本站部分内容来自互联网,一切版权均归源网站或源作者所有。
如果侵犯了你的权益请来信告知我们删除。邮箱：cc@cccx.cn
下一篇：静态资源处理策略
