696 lines
13 KiB
Markdown
696 lines
13 KiB
Markdown
---
|
|
tags: [DEV, VITE, configuration, typescript]
|
|
create time: 2026-04-18
|
|
---
|
|
|
|
# Vite 配置详解
|
|
|
|
## 配置文件结构
|
|
|
|
Vite 配置文件支持多种格式：`vite.config.js`、`vite.config.ts`，推荐使用 TypeScript 获得类型提示。
|
|
|
|
完整配置结构示例：
|
|
|
|
```typescript
|
|
import { defineConfig } from 'vite'
|
|
import react from '@vitejs/plugin-react'
|
|
import path from 'path'
|
|
|
|
export default defineConfig({
|
|
// 插件配置
|
|
plugins: [react()],
|
|
|
|
// 路径别名
|
|
resolve: {
|
|
alias: {
|
|
'@': path.resolve(__dirname, './src'),
|
|
'@components': path.resolve(__dirname, './src/components'),
|
|
'@hooks': path.resolve(__dirname, './src/hooks')
|
|
}
|
|
},
|
|
|
|
// 开发服务器配置
|
|
server: {
|
|
port: 3000,
|
|
host: true,
|
|
open: true,
|
|
cors: true
|
|
},
|
|
|
|
// 构建配置
|
|
build: {
|
|
outDir: 'dist',
|
|
sourcemap: true
|
|
}
|
|
})
|
|
```
|
|
|
|
## 核心配置项
|
|
|
|
### resolve 模块解析
|
|
|
|
#### 路径别名
|
|
```typescript
|
|
resolve: {
|
|
alias: {
|
|
'@': path.resolve(__dirname, './src'),
|
|
// 支持目录别名
|
|
'@components': path.resolve(__dirname, './src/components'),
|
|
'@utils': path.resolve(__dirname, './src/utils')
|
|
}
|
|
}
|
|
```
|
|
|
|
#### 扩展名解析
|
|
```typescript
|
|
resolve: {
|
|
extensions: ['.js', '.jsx', '.ts', '.tsx', '.json']
|
|
}
|
|
```
|
|
|
|
### server 开发服务器
|
|
|
|
```typescript
|
|
server: {
|
|
// 端口配置
|
|
port: 3000,
|
|
strictPort: false, // 端口被占用时自动尝试下一个
|
|
host: true, // 监听所有网络地址
|
|
|
|
// 自动打开浏览器
|
|
open: true,
|
|
openPage: '/dashboard',
|
|
|
|
// CORS 配置
|
|
cors: true,
|
|
|
|
// 代理配置
|
|
proxy: {
|
|
'/api': {
|
|
target: 'http://localhost:8080',
|
|
changeOrigin: true,
|
|
rewrite: (path) => path.replace(/^\/api/, '')
|
|
},
|
|
'/assets': {
|
|
target: 'http://localhost:9000',
|
|
changeOrigin: true
|
|
}
|
|
},
|
|
|
|
// HMR 配置
|
|
hmr: {
|
|
overlay: true, // 显示错误覆盖层
|
|
port: 24678 // HMR WebSocket 端口
|
|
},
|
|
|
|
// 中间件模式 (用于 SSR)
|
|
middlewareMode: false
|
|
}
|
|
```
|
|
|
|
### load 环境变量
|
|
|
|
```bash
|
|
# .env.development
|
|
VITE_API_URL=http://localhost:8080/api
|
|
VITE_APP_NAME=Dev Environment
|
|
|
|
# .env.production
|
|
VITE_API_URL=https://api.example.com
|
|
VITE_APP_NAME=Production
|
|
```
|
|
|
|
```typescript
|
|
// 类型定义
|
|
interface ImportMetaEnv {
|
|
readonly VITE_API_URL: string
|
|
readonly VITE_APP_NAME: string
|
|
}
|
|
|
|
// 使用环境变量
|
|
const apiUrl = import.meta.env.VITE_API_URL
|
|
const appName = import.meta.env.VITE_APP_NAME
|
|
|
|
// 自定义环境变量访问
|
|
export default defineConfig(({ mode }) => {
|
|
return {
|
|
define: {
|
|
__APP_VERSION__: JSON.stringify(process.env.npm_package_version),
|
|
__ENV__: JSON.stringify(mode)
|
|
}
|
|
}
|
|
})
|
|
```
|
|
|
|
### build 构建配置
|
|
|
|
```typescript
|
|
build: {
|
|
// 输出目录
|
|
outDir: 'dist',
|
|
assetsDir: 'assets',
|
|
|
|
// Source Map 配置
|
|
sourcemap: false, // 生产环境关闭
|
|
sourcemapExcludeSources: false,
|
|
|
|
// 压缩配置
|
|
minify: 'terser', // terser | esbuild
|
|
terserOptions: {
|
|
compress: {
|
|
drop_console: true, // 移除 console
|
|
drop_debugger: true, // 移除 debugger
|
|
pure_funcs: ['console.log', 'console.info']
|
|
}
|
|
},
|
|
|
|
// 代码分割配置
|
|
rollupOptions: {
|
|
output: {
|
|
// 手动代码分割
|
|
manualChunks: {
|
|
'vendor-react': ['react', 'react-dom'],
|
|
'vendor-ui': ['antd', '@ant-design/icons'],
|
|
'vendor-utils': ['lodash', 'dayjs']
|
|
},
|
|
// 文件名模式
|
|
chunkFileNames: 'js/[name]-[hash].js',
|
|
entryFileNames: 'js/[name]-[hash].js',
|
|
assetFileNames: '[ext]/[name]-[hash].[ext]'
|
|
}
|
|
},
|
|
|
|
// 构建优化
|
|
chunkSizeWarningLimit: 1000, // 警告限制
|
|
rollupOptions: {
|
|
output: {
|
|
// 内联动态导入
|
|
inlineDynamicImports: false,
|
|
// 保留模块结构
|
|
preserveModules: false
|
|
}
|
|
},
|
|
cssCodeSplit: true,
|
|
reportCompressedSize: false,
|
|
target: 'es2015'
|
|
}
|
|
```
|
|
|
|
### preview 预览配置
|
|
|
|
```typescript
|
|
preview: {
|
|
port: 4173,
|
|
strictPort: false,
|
|
host: true,
|
|
open: true,
|
|
|
|
// 预览服务器配置
|
|
cors: true,
|
|
|
|
// 中间件
|
|
middlewares: [
|
|
// 自定义中间件
|
|
]
|
|
}
|
|
```
|
|
|
|
## CSS 配置
|
|
|
|
### CSS Modules
|
|
```typescript
|
|
css: {
|
|
modules: {
|
|
// 命名规范
|
|
localsConvention: 'camelCase', // camelCase | camelCaseOnly | dashes | dashesOnly
|
|
|
|
// 作用域行为
|
|
scopeBehaviour: 'local', // local | global
|
|
|
|
// 类名生成
|
|
generateScopedName: '[name]__[local]___[hash:base64:5]',
|
|
|
|
// Hash 生成函数
|
|
hashPrefix: 'prefix',
|
|
|
|
// 全局模块路径
|
|
globalModulePaths: [/node_modules/]
|
|
}
|
|
}
|
|
```
|
|
|
|
### CSS 预处理器
|
|
```typescript
|
|
css: {
|
|
preprocessorOptions: {
|
|
scss: {
|
|
additionalData: `@import "@/styles/variables.scss";`,
|
|
api: 'modern-compiler' // 使用现代编译器
|
|
},
|
|
less: {
|
|
modifyVars: {
|
|
'primary-color': '#1890ff'
|
|
},
|
|
javascriptEnabled: true
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### PostCSS 配置
|
|
```javascript
|
|
// postcss.config.js
|
|
export default {
|
|
plugins: {
|
|
autoprefixer: {},
|
|
'cssnano': {
|
|
preset: 'default'
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## 插件系统
|
|
|
|
### 插件配置流程
|
|
|
|
```mermaid
|
|
graph TD
|
|
A[vite.config.ts] --> B[插件导入]
|
|
B --> C[插件配置]
|
|
C --> D[插件注册]
|
|
D --> E[构建流程]
|
|
E --> F[插件执行]
|
|
```
|
|
|
|
### 官方插件
|
|
|
|
#### React 插件
|
|
```typescript
|
|
import react from '@vitejs/plugin-react'
|
|
|
|
export default defineConfig({
|
|
plugins: [
|
|
react({
|
|
// Babel 转换
|
|
babel: {
|
|
plugins: ['emotion']
|
|
},
|
|
// JSX 运行时
|
|
jsxRuntime: 'automatic', // classic | automatic
|
|
// 开发工具
|
|
devtools: true,
|
|
// 包含
|
|
include: /\.(jsx|js|tsx|ts)$/,
|
|
// 排除
|
|
exclude: /\.node_modules/
|
|
})
|
|
]
|
|
})
|
|
```
|
|
|
|
#### Vue 插件
|
|
```typescript
|
|
import vue from '@vitejs/plugin-vue'
|
|
|
|
export default defineConfig({
|
|
plugins: [
|
|
vue({
|
|
// Vue 编译器选项
|
|
template: {
|
|
compilerOptions: {
|
|
isCustomElement: (tag) => tag.includes('-'),
|
|
whitespace: 'condense'
|
|
}
|
|
},
|
|
// 脚本配置
|
|
script: {
|
|
defineModel: true,
|
|
propsDestructure: true
|
|
},
|
|
// 样式配置
|
|
style: {
|
|
scoped: true
|
|
}
|
|
})
|
|
]
|
|
})
|
|
```
|
|
|
|
### 自定义插件
|
|
|
|
#### 基础插件结构
|
|
```typescript
|
|
import type { Plugin } from 'vite'
|
|
|
|
export function myCustomPlugin(): Plugin {
|
|
return {
|
|
name: 'my-custom-plugin',
|
|
|
|
// 配置阶段
|
|
config(config) {
|
|
return {
|
|
// 返回配置修改
|
|
}
|
|
},
|
|
|
|
configResolved(config) {
|
|
// 配置已解析
|
|
console.log('Vite config resolved:', config)
|
|
},
|
|
|
|
// 配置开发服务器
|
|
configureServer(server) {
|
|
// 自定义服务器中间件
|
|
server.middlewares.use((req, res, next) => {
|
|
if (req.url === '/custom-endpoint') {
|
|
res.statusCode = 200
|
|
res.setHeader('Content-Type', 'application/json')
|
|
res.end(JSON.stringify({ message: 'Custom response' }))
|
|
} else {
|
|
next()
|
|
}
|
|
})
|
|
|
|
// 返回清理函数
|
|
return () => {
|
|
console.log('Server closed')
|
|
}
|
|
},
|
|
|
|
// 转换钩子
|
|
transform(code, id) {
|
|
// 转换代码
|
|
if (id.endsWith('.custom')) {
|
|
return {
|
|
code: convertCustomFormat(code),
|
|
map: null
|
|
}
|
|
}
|
|
},
|
|
|
|
// 模块解析钩子
|
|
resolveId(source) {
|
|
// 自定义模块解析
|
|
if (source === 'virtual-module') {
|
|
return '\0virtual-module'
|
|
}
|
|
},
|
|
|
|
// 加载钩子
|
|
load(id) {
|
|
// 加载模块内容
|
|
if (id === '\0virtual-module') {
|
|
return 'export const msg = "Hello from virtual module"'
|
|
}
|
|
},
|
|
|
|
// 构建钩子
|
|
buildStart() {
|
|
console.log('Build started')
|
|
},
|
|
|
|
buildEnd() {
|
|
console.log('Build completed')
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
#### 环境变量插件
|
|
```typescript
|
|
import type { Plugin } from 'vite'
|
|
|
|
export function envPlugin(): Plugin {
|
|
return {
|
|
name: 'env-plugin',
|
|
config(config, { mode }) {
|
|
// 加载环境变量
|
|
const env = loadEnv(mode, process.cwd(), '')
|
|
|
|
return {
|
|
define: {
|
|
'import.meta.env': JSON.stringify(env)
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 第三方插件推荐
|
|
|
|
#### 路径别名插件
|
|
```typescript
|
|
import { viteCommonjs } from '@originjs/vite-plugin-commonjs'
|
|
|
|
export default defineConfig({
|
|
plugins: [
|
|
react(),
|
|
viteCommonjs() // 支持 CommonJS 模块
|
|
]
|
|
})
|
|
```
|
|
|
|
#### 压缩插件
|
|
```typescript
|
|
import viteCompression from 'vite-plugin-compression'
|
|
|
|
export default defineConfig({
|
|
plugins: [
|
|
viteCompression({
|
|
verbose: true,
|
|
disable: false,
|
|
threshold: 10240,
|
|
algorithm: 'gzip',
|
|
ext: '.gz'
|
|
})
|
|
]
|
|
})
|
|
```
|
|
|
|
#### 组件按需加载
|
|
```typescript
|
|
import Components from 'unplugin-vue-components/vite'
|
|
import { AntDesignVueResolver } from 'unplugin-vue-components/resolvers'
|
|
|
|
export default defineConfig({
|
|
plugins: [
|
|
Components({
|
|
resolvers: [
|
|
AntDesignVueResolver()
|
|
]
|
|
})
|
|
]
|
|
})
|
|
```
|
|
|
|
## TypeScript 配置
|
|
|
|
### tsconfig.json
|
|
```json
|
|
{
|
|
"compilerOptions": {
|
|
"target": "ES2020",
|
|
"useDefineForClassFields": true,
|
|
"lib": ["ES2020", "DOM", "DOM.Iterable"],
|
|
"module": "ESNext",
|
|
"skipLibCheck": true,
|
|
"moduleResolution": "bundler",
|
|
"allowImportingTsExtensions": true,
|
|
"resolveJsonModule": true,
|
|
"isolatedModules": true,
|
|
"noEmit": true,
|
|
"jsx": "react-jsx",
|
|
"strict": true,
|
|
"noUnusedLocals": true,
|
|
"noUnusedParameters": true,
|
|
"noFallthroughCasesInSwitch": true,
|
|
"baseUrl": ".",
|
|
"paths": {
|
|
"@/*": ["src/*"]
|
|
}
|
|
},
|
|
"include": ["src", "vite.config.ts"],
|
|
"references": [{ "path": "./tsconfig.node.json" }]
|
|
}
|
|
```
|
|
|
|
### tsconfig.node.json (为 Vite 配置文件提供类型)
|
|
```json
|
|
{
|
|
"compilerOptions": {
|
|
"composite": true,
|
|
"skipLibCheck": true,
|
|
"module": "ESNext",
|
|
"moduleResolution": "bundler",
|
|
"allowSyntheticDefaultImports": true,
|
|
"strict": true
|
|
},
|
|
"include": ["vite.config.ts"]
|
|
}
|
|
```
|
|
|
|
## 高级配置
|
|
|
|
### 多入口配置
|
|
```typescript
|
|
import { defineConfig } from 'vite'
|
|
import path from 'path'
|
|
|
|
export default defineConfig({
|
|
build: {
|
|
rollupOptions: {
|
|
input: {
|
|
main: path.resolve(__dirname, 'index.html'),
|
|
admin: path.resolve(__dirname, 'admin.html'),
|
|
landing: path.resolve(__dirname, 'landing.html')
|
|
}
|
|
}
|
|
}
|
|
})
|
|
```
|
|
|
|
### 库模式配置
|
|
```typescript
|
|
export default defineConfig({
|
|
build: {
|
|
lib: {
|
|
entry: path.resolve(__dirname, 'src/index.ts'),
|
|
name: 'MyLibrary',
|
|
fileName: (format) => `my-library.${format}.js`,
|
|
formats: ['es', 'umd']
|
|
},
|
|
rollupOptions: {
|
|
external: ['react', 'react-dom'],
|
|
output: {
|
|
globals: {
|
|
react: 'React',
|
|
'react-dom': 'ReactDOM'
|
|
}
|
|
}
|
|
}
|
|
}
|
|
})
|
|
```
|
|
|
|
### SSR 配置
|
|
```typescript
|
|
export default defineConfig({
|
|
build: {
|
|
ssr: true, // 启用 SSR
|
|
outDir: 'dist/server', // SSR 输出目录
|
|
rollupOptions: {
|
|
input: './src/entry-server.ts'
|
|
}
|
|
},
|
|
server: {
|
|
middlewareMode: 'ssr' // SSR 模式
|
|
}
|
|
})
|
|
```
|
|
|
|
## 配置最佳实践
|
|
|
|
### 环境分离
|
|
```typescript
|
|
// vite.config.ts
|
|
export default defineConfig(({ mode }) => {
|
|
return {
|
|
plugins: [
|
|
mode === 'development' ? devPlugin() : prodPlugin()
|
|
],
|
|
server: mode === 'development' ? devServerConfig : {}
|
|
}
|
|
})
|
|
```
|
|
|
|
### 配置复用
|
|
```typescript
|
|
// shared-config.ts
|
|
export const baseConfig = {
|
|
resolve: {
|
|
alias: {
|
|
'@': path.resolve(__dirname, './src')
|
|
}
|
|
}
|
|
}
|
|
|
|
export const devConfig = {
|
|
...baseConfig,
|
|
server: {
|
|
port: 3000
|
|
}
|
|
}
|
|
|
|
export const buildConfig = {
|
|
...baseConfig,
|
|
build: {
|
|
outDir: 'dist'
|
|
}
|
|
}
|
|
```
|
|
|
|
### 配置验证
|
|
```typescript
|
|
function validateConfig(config: UserConfig) {
|
|
if (!config.plugins) {
|
|
throw new Error('Plugins are required')
|
|
}
|
|
|
|
// 验证路径别名
|
|
if (config.resolve?.alias) {
|
|
Object.entries(config.resolve.alias).forEach(([key, value]) => {
|
|
if (!path.isAbsolute(value)) {
|
|
throw new Error(`Alias ${key} must be an absolute path`)
|
|
}
|
|
})
|
|
}
|
|
}
|
|
```
|
|
|
|
## 故障排查
|
|
|
|
### 配置加载问题
|
|
```bash
|
|
# 调试配置加载
|
|
DEBUG=vite:config npm run dev
|
|
|
|
# 检查配置语法
|
|
node -c vite.config.ts
|
|
```
|
|
|
|
### 路径解析问题
|
|
```typescript
|
|
// 使用 debug 插件检查路径
|
|
import { defineConfig } from 'vite'
|
|
|
|
export default defineConfig({
|
|
resolve: {
|
|
alias: {
|
|
'debug': require.resolve('debug')
|
|
}
|
|
}
|
|
})
|
|
```
|
|
|
|
### 插件冲突诊断
|
|
```typescript
|
|
// 在插件开发中添加日志
|
|
export function debugPlugin() {
|
|
return {
|
|
name: 'debug-plugin',
|
|
transform(code, id) {
|
|
console.log('Transforming:', id)
|
|
return null
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
配置是 Vite 项目的核心，合理的配置能显著提升开发体验和构建质量。根据项目规模和需求，逐步完善配置是最佳实践。
|
|
|
|
相关文档：
|
|
- [[DEV/VITE/架构原理.md]] - 理解配置的底层机制
|
|
- [[DEV/VITE/优化实践.md]] - 配置优化技巧
|