基本配置
约 1229 字大约 4 分钟
2025-10-23
基本配置
Vite 的开发体验来自“职责分层”:
- 开发期以原生 ESM + 快速转译为主
- 构建期交给成熟打包链路处理产物
Vite 与 Oxc 的关系(先讲清概念)
很多同学会把 Vite、esbuild、Rolldown、Oxc 混在一起。
在你当前这套笔记里,可以先按这个认知使用:
- Vite 的核心是“统一开发与构建体验”的工程框架。
Oxc更像高性能编译基础设施,在新一代打包生态中出现频率更高。- 你在项目里是否直接使用 Oxc,不影响先掌握 Vite 的基础配置方法。
base
用于在 嵌套的公共路径下部署项目 时,重写资源路径
vite.config.ts
import { defineConfig } from 'vite'
/**
* 例如在本地开发环境中使用的是 http://localhost:5173/
* 而在实际线上部署时使用的是 https://example.com/admin/
* 那么需要将 base 配置为 /admin/
*/
export default defineConfig({
// 例如部署到 https://example.com/admin/
base: '/admin/',
})resolve
用于进行模块解析(Module Resolution)配置,专门用来告诉 Vite 如何查找和解析代码中的 import / require 语句
| 配置项 | 作用 | 常见写法 | 使用注意 |
|---|---|---|---|
alias | 配置路径别名 | @ -> /src | 要和 tsconfig.json 保持一致 |
extensions | 自动补全扩展名 | ['.ts','.js'] | 不建议塞太多,避免误解析 |
dedupe | 强制依赖单实例 | ['vue'] | 解决 monorepo 或软链接重复实例 |
conditions | 条件导出匹配 | ['browser'] | 仅在特殊包分发策略下使用 |
preserveSymlinks | 是否保留软链接路径 | true/false | monorepo 调试时偶尔需要 |
import { defineConfig } from 'vite'
import { resolve } from 'node:path'
export default defineConfig({
resolve: {
alias: {
'@': resolve(__dirname, 'src'),
'~components': resolve(__dirname, 'src/components'),
},
dedupe: ['vue'],
},
})server
用于配置开发服务器
| 配置项 | 作用 | 常见写法 | 使用注意 |
|---|---|---|---|
host | 监听地址 | '0.0.0.0' | 便于局域网设备联调 |
port | 开发端口 | 5173 | 固定端口便于团队协作 |
strictPort | 端口被占用是否退出 | true | 避免自动换端口导致联调混乱 |
open | 启动后自动打开浏览器 | true | 在远程开发环境通常关闭 |
proxy | 接口代理 | '/api' -> target | 仅 dev 生效,prod 仍需网关 |
hmr | 热更新策略 | { overlay: true } | 可关闭报错浮层做定制处理 |
import { defineConfig } from 'vite'
export default defineConfig({
server: {
host: '0.0.0.0',
port: 5173,
strictPort: true,
open: true,
proxy: {
'/api': {
target: 'http://localhost:8080',
changeOrigin: true,
// /api/users -> /users
rewrite: (path) => path.replace(/^\/api/, ''),
},
},
},
})define
用于定义全局常量替换,在开发环境下其值会被定义在全局,在构件时将直接被静态替换
笔记
若使用 TypeScript 则需要额外在 vite-env.d.ts 中添加声明以及类型
vite.config.ts
import { defineConfig } from 'vite'
export default defineConfig({
define: {
__APP_VERSION__: JSON.stringify('1.0.0'),
__BUILD_TIME__: JSON.stringify(new Date().toISOString()),
},
})vite-env.d.ts
declare const __APP_VERSION__: string
declare const __BUILD_TIME__: stringindex.ts
console.log(__APP_VERSION__)css
用于配置 CSS 处理相关行为的,包括预处理器(Sass/Less)、PostCSS、CSS Modules、源码映射等
可配置项
css.postcss:配置 PostCSS 插件链css.preprocessorOptions:配置 Sass/Less 等预处理器全局注入与编译参数css.modules:配置 CSS Modules 命名策略与作用域行为css.devSourcemap:控制开发环境 CSS sourcemap
import { defineConfig } from 'vite'
export default defineConfig({
css: {
// 1. PostCSS 配置
postcss: {
plugins: [
require('autoprefixer'),
require('tailwindcss'), // 或 @tailwindcss/vite 插件方式
]
},
// 2. 预处理器全局配置
preprocessorOptions: {
scss: {
additionalData: `@use "@/styles/variables.scss" as *;
@use "@/styles/mixins.scss" as *;`, // 全局注入变量和 mixin
silenceDeprecations: ['legacy-js-api'], // 关闭 Sass 废弃警告
},
less: {
javascriptEnabled: true,
additionalData: '@import "@/styles/variables.less";',
}
},
// 3. CSS Modules 配置
modules: {
localsConvention: 'camelCaseOnly', // class 名转为驼峰
scopeBehaviour: 'local', // 默认 local
generateScopedName: '[name]__[local]___[hash:base64:5]', // 自定义 hash
},
// 4. 开发环境 source map
devSourcemap: true, // 方便调试
},
})publicDir
用于存放 "不需要经过构建处理" 的静态文件(如 favicon.ico)
vite.config.ts
import { defineConfig } from 'vite'
export default defineConfig({
// 默认是 public;可以改目录,也可以设为 false 关闭
publicDir: 'public',
})index.html
<!-- public/logo.svg -> 直接以 /logo.svg 访问 -->
<img src="/logo.svg" alt="logo" />build
用于控制 vite 打包行为
常用配置项
| 配置项 | 作用 | 常见写法 | 说明 |
|---|---|---|---|
target | 指定产物语法目标 | 'es2018' | 兼容性与体积需要平衡 |
outDir | 输出目录 | 'dist' | 部署目录通常直接指向这里 |
assetsDir | 静态资源子目录 | 'assets' | 便于部署侧做资源策略 |
sourcemap | 生成 sourcemap | true/false/'hidden' | 生产环境常用 hidden |
minify | 压缩方式 | 'oxc' | 默认即可,除非有特殊要求 |
cssCodeSplit | CSS 是否拆分 | true/false | 多页面/异步场景建议开启 |
assetsInlineLimit | 小资源内联阈值 | 4096 | 阈值过大会放大 JS 体积 |
manifest | 生成清单文件 | true | 后端模板注入静态资源常用 |
rollupOptions | 深度构建控制 | { output: { ... } } | 详见 Rollup 章节 |
vite.config.ts
import { defineConfig } from 'vite'
export default defineConfig({
build: {
target: 'es2018',
outDir: 'dist',
assetsDir: 'assets',
sourcemap: false,
minify: 'esbuild',
cssCodeSplit: true,
assetsInlineLimit: 4096,
manifest: true,
rollupOptions: {
output: {
manualChunks: {
// 把第三方依赖拆到 vendor,减少业务 chunk 抖动
vendor: ['vue', 'vue-router'],
},
},
},
},
})