Vite配置详解：从入门到精通
Vite 是一款由 Vue.js 作者尤雨溪开发的现代前端构建工具，它以其极速的开发服务器启动速度和闪电般的模块热更新 (HMR) 而闻名。Vite 利用浏览器原生的 ES Modules (ESM) 能力，在开发环境下跳过了打包步骤，直接提供模块给浏览器，从而大幅提升了开发体验。在生产环境下，Vite 采用 Rollup 进行打包，兼顾了性能和优化。
本篇文档将深入探讨 Vite 的核心配置，帮助开发者充分利用 Vite 的能力。
核心思想：
Vite 的配置以 vite.config.ts (或 .js) 文件为中心，使用 ESM 模块导出配置对象。它通过 plugins 数组扩展功能，通过 server 配置开发服务器，build 配置生产构建，resolve 配置模块解析，以及 css、json 等全局配置项，实现了高度可定制性和灵活性。
一、Vite 配置文件的基本结构
Vite 的配置文件通常命名为 vite.config.js 或 vite.config.ts，位于项目根目录。它是一个 ESM 模块，负责导出一个配置对象。
1 | // vite.config.ts |
关键点：
defineConfig：虽然不是必需的，但强烈建议使用defineConfig函数来包裹配置对象。这提供了智能提示 (IntelliSense) 和类型检查，帮助避免配置错误。- ESM 模块：配置文件必须遵循 ES Modules 规范，使用
import和export default。
二、核心配置选项详解
Vite 的配置选项非常丰富，以下将对一些常用且重要的配置进行详细解析。
2.1 root
- 类型：
string - 默认值：
process.cwd()(项目根目录) - 描述：项目根目录（
index.html文件所在的位置）。可以直接通过命令行vite --root <path>指定。
2.2 base
- 类型：
string - 默认值：
/ - 描述：公共基础路径。
- 在开发或生产构建时，如果你的部署会到一个非根路径，需要设置此项。
- 例如，如果应用部署在
https://www.example.com/my-app/，则base应设置为/my-app/。 - Vite 会自动将所有引用（包括资源 URL 和绝对路径）调整到此基础路径。
2.3 mode
- 类型：
string - 默认值：
'development'(开发环境) /'production'(生产环境) - 描述：运行模式。Vite 会根据
--mode命令行选项自动设置。在开发时通常是development，打包时是production。可以通过此选项来加载不同的环境变量。
2.4 plugins
- 类型：
Array<PluginOption | (PluginOption | PluginOption[])[]> - 描述：一个数组，用于配置 Vite 插件。插件是 Vite 扩展其核心功能的主要方式，例如支持 Vue、React、TypeScript、图片优化等。
- 示例：
1
2
3
4
5
6
7
8
9
10import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import basicSsl from '@vitejs/plugin-basic-ssl'; // 一个用于 HTTPS 开发的插件
export default defineConfig({
plugins: [
vue(),
basicSsl() // 启用 HTTPS 开发服务器
]
});
- 示例：
2.5 publicDir
- 类型：
string | false - 默认值：
'public' - 描述：静态资源服务的目录。此目录下的文件会直接被服务，不会经过构建流程。
- 在开发服务器中，直接通过
/访问。例如public/logo.png可通过http://localhost:3000/logo.png访问。 - 在构建时，会被复制到
outDir根目录。 - 如果设置为
false，则禁用公共文件服务。
- 在开发服务器中，直接通过
2.6 cacheDir
- 类型：
string - 默认值：
'node_modules/.vite' - 描述：存储缓存文件的目录。Vite 将优化过的依赖缓存到此目录，以提高后续启动速度和构建速度。
2.7 resolve
- 类型：
ResolveOptions - 描述：配置模块解析的策略。
2.7.1 resolve.alias
- 类型：
Record<string, string> | Array<{ find: string | RegExp, replacement: string, customResolver?: ResolverFunction }> - 描述：路径别名。用于模块导入时创建别名，使导入路径更简洁。
- 示例：
1
2
3
4
5
6
7
8
9
10
11
12// vite.config.ts
import { defineConfig } from 'vite';
import { resolve } from 'path'; // 导入 path 模块
export default defineConfig({
resolve: {
alias: {
'@': resolve(__dirname, './src'), // @ 符号指向 src 目录
'#': resolve(__dirname, './types') // # 符号指向 types 目录
}
}
}); - 通过这样配置后，在代码中你可以使用
import Component from '@/components/Component.vue'而不是import Component from '../../components/Component.vue'。
- 示例：
2.7.2 resolve.dedupe
- 类型：
string[] - 描述：在开发环境下，强制 Vite 始终将列出的依赖项解析到同一副本。这在 monorepo 或依赖项被多次引用但需要确保它们是同一个实例时很有用。
2.7.3 resolve.extensions
- 类型：
string[] - 默认值：
['.mjs', '.js', '.ts', '.jsx', '.tsx', '.json', '.vue'] - 描述：导入时可省略的扩展名列表。
2.8 css
- 类型：
CSSOptions - 描述：配置 CSS 预处理器、CSS Modules 等。
2.8.1 css.preprocessorOptions
- 类型：
Record<string, Record<string, any>> - 描述：指定 CSS 预处理器的选项。
- 示例 (SCSS)：
1
2
3
4
5
6
7
8
9
10
11
12// vite.config.ts
import { defineConfig } from 'vite';
export default defineConfig({
css: {
preprocessorOptions: {
scss: {
additionalData: `@import "@/styles/variables.scss";` // 自动向所有 SCSS 文件注入变量
}
}
}
});
- 示例 (SCSS)：
2.8.2 css.modules
- 类型：
CSSModulesOptions - 描述：配置 CSS Modules 的行为。
2.9 json
- 类型：
JSONOptions - 描述：配置 JSON 导入的行为。
2.9.1 json.namedExports
- 类型：
boolean - 默认值：
true - 描述：是否支持 JSON 文件的命名导出。
2.10 esbuild
- 类型：
ESBuildOptions | false - 描述：ESBuild 是 Vite 默认用于代码转译和压缩的工具。可以配置其选项或禁用它。
2.10.1 esbuild.jsxFactory / esbuild.jsxFragment
- 类型：
string - 描述：JSX 转译为
React.createElement(或其他) 调用的工厂函数。
2.11 server
- 类型：
ServerOptions - 描述：配置开发服务器。
2.11.1 server.host
- 类型：
string | boolean - 默认值：
'localhost' - 描述：指定服务器监听的 IP 地址。
'localhost'：只能通过本地访问。'0.0.0.0'或true：可以从局域网 IP 访问，便于移动端调试。'127.0.0.1'：默认。
2.11.2 server.port
- 类型：
number - 默认值：
5173 - 描述：指定开发服务器端口。如果端口被占用，Vite 会自动尝试下一个可用端口。
2.11.3 server.strictPort
- 类型：
boolean - 默认值：
false - 描述：如果端口被占用，是否严格退出而不是尝试下一个可用端口。
2.11.4 server.https
- 类型：
boolean | Http2ServerOptions - 默认值：
false - 描述：是否启用 HTTPS (TLS)。需要配置 SSL 证书。
- 可以使用
@vitejs/plugin-basic-ssl插件来快速启用自签名证书。
- 可以使用
2.11.5 server.open
- 类型：
boolean | string - 默认值：
false - 描述：服务器启动后是否自动打开浏览器。
true：打开默认浏览器。string：指定要打开的 URL 路径 (如/dashboard)。
2.11.6 server.proxy
- 类型：
Record<string, string | ProxyOptions> - 描述：配置代理规则，将特定路径的请求转发到其他服务器。解决跨域问题。
- 示例：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18// vite.config.ts
import { defineConfig } from 'vite';
export default defineConfig({
server: {
proxy: {
'/api': {
target: 'http://localhost:8080', // 后端 API 服务器地址
changeOrigin: true, // 改变源，使其符合后端服务器的源
rewrite: (path) => path.replace(/^\/api/, '') // 重写路径，将 /api 替换为空
},
'/socket.io': {
target: 'ws://localhost:8080',
ws: true // 针对 WebSocket
}
}
}
});
- 示例：
2.11.7 server.hmr
- 类型：
boolean | HmrOptions - 默认值：
true - 描述：配置 WebSocket 服务器。如果需要，可以禁用 HMR 或配置 HMR 的连接选项。
2.11.8 server.cors
- 类型：
boolean | CorsOptions - 默认值：
false - 描述：是否允许 CORS。设置为
true会允许所有来源的请求。
2.12 build
- 类型：
BuildOptions - 描述：配置生产构建。
2.12.1 build.target
- 类型：
string | string[] - 默认值：
'modules'(支持原生 ESM 的浏览器) - 描述：设置最终构建的浏览器兼容目标。
'es2015'等 ES 版本：转译到指定 ES 版本。['es2015', 'chrome58', 'ios10']：多个目标。
2.12.2 build.outDir
- 类型：
string - 默认值：
'dist' - 描述：指定输出目录。
2.12.3 build.assetsDir
- 类型：
string - 默认值：
'assets' - 描述：指定在
outDir中的静态资源存放目录。
2.12.4 build.assetsInlineLimit
- 类型：
number - 默认值：
4096(4KB) - 描述：小于此阈值的导入或引用的资源将内联为 base64 编码。设置为
0可以完全禁用内联。
2.12.5 build.cssCodeSplit
- 类型：
boolean - 默认值：
true - 描述：是否启用 CSS 代码分割。如果设置为
false，整个项目的 CSS 将被抽离到一个 CSS 文件中。
2.12.6 build.sourcemap
- 类型：
boolean | 'inline' | 'hidden' - 默认值：
false - 描述：是否生成 Source Map 文件。
true：生成 Source Map。'inline'：Source Map 以 Data URI 的形式内联到输出文件中。'hidden'：生成 Source Map 但不在源文件中引用。
2.12.7 build.minify
- 类型：
boolean | 'terser' | 'esbuild' - 默认值：
'esbuild' - 描述：指定使用哪种压缩器。
'terser'：使用 Terser 进行压缩，提供更多配置选项，但速度较慢。'esbuild'：使用 Esbuild 进行压缩，速度极快，但配置选项有限。false：禁用压缩。
2.12.8 build.emptyOutDir
- 类型：
boolean - 默认值：
true - 描述：在构建时清空
outDir目录。
2.12.9 build.rollupOptions
- 类型：
rollup.RollupOptions - 描述：直接配置底层 Rollup 打包器的选项。提供了对打包过程更细粒度的控制，例如配置多个入口、高级代码分割等。
- 示例 (配置多入口)：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15// vite.config.ts
import { defineConfig } from 'vite';
import { resolve } from 'path';
export default defineConfig({
build: {
rollupOptions: {
input: {
main: resolve(__dirname, 'index.html'),
admin: resolve(__dirname, 'admin.html'),
nested: resolve(__dirname, 'nested/index.html')
}
}
}
});
- 示例 (配置多入口)：
2.13 preview
- 类型：
PreviewOptions - 描述：配置
vite preview命令的行为，用于在本地预览生产构建的文件。- 选项与
server类似，如preview.host、preview.port、preview.open等。
- 选项与
2.14 optimizeDeps
- 类型：
DepOptimizationOptions - 描述：配置依赖预构建行为。Vite 在开发服务器启动时会使用 Esbuild 对
node_modules中的依赖进行预构建 (Pre-bundling)，将其转换为 ESM 格式，以加快浏览器加载速度并解决 CommonJS/UMD 兼容性问题。
2.14.1 optimizeDeps.include
- 类型：
string[] - 描述：强制包含在预构建中的依赖项。当某些库没有被自动检测到或需要手动优化时使用。
- 例如：
['lodash']。
- 例如：
2.14.2 optimizeDeps.exclude
- 类型：
string[] - 描述：从预构建中排除的依赖项。有时某些库不需要预构建或会引起问题。
- 例如：
['my-problematic-library']。
- 例如：
三、环境变量
Vite 通过 import.meta.env 暴露环境变量。
import.meta.env.MODE：当前模式 (development或production)。import.meta.env.BASE_URL：base配置项的值。import.meta.env.PROD：是否是生产环境 (boolean)。import.meta.env.DEV：是否是开发环境 (boolean)。
除了这些内置变量，你还可以通过 envDir 选项和 .env 文件来加载自定义环境变量。
envDir
- 类型：
string - 默认值：
process.cwd() - 描述：加载
.env文件的目录。
.env 文件
Vite 会根据当前模式加载相应的 .env 文件：
.env：所有模式加载。.env.local：所有模式加载，但会被.gitignore忽略，适用于本地环境特定配置。.env.[mode]：特定模式加载 (例如.env.development、.env.production)。.env.[mode].local：特定模式加载，且会被.gitignore忽略。
加载优先级 (从高到低)：
.env.[mode].local.env.[mode].env.local.env
注意： 只有以 VITE_ 开头的自定义环境变量才会在客户端暴露。例如，在 .env 文件中定义 VITE_APP_TITLE=My App，然后在代码中可以通过 import.meta.env.VITE_APP_TITLE 访问。
1 | // .env.development |
四、总结
Vite 凭借其出色的性能和极佳的开发体验，已成为现代前端开发的主流构建工具之一。通过灵活的配置文件 vite.config.ts，开发者可以根据项目需求定制开发服务器、生产构建、模块解析、CSS 处理以及插件扩展等各个方面的行为。深入理解并合理配置这些选项，将能最大化地发挥 Vite 的优势，提升开发效率和应用性能。
本博客所有文章除特别声明外，均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来源 1024 维度！
相关推荐
2024-07-04
Electron 开发详解
Electron (原名 Atom Shell) 是一个由 GitHub 开发的开源框架，它允许你使用 Web 技术 (HTML, CSS, JavaScript) 来构建跨平台的桌面应用程序。通过将 Chromium 渲染引擎和 Node.js 运行时集成到一个单一的项目中，Electron 使得前端开发者只需掌握一套技术栈，就能创建出功能强大、拥有原生外观和感觉的桌面应用，并能够访问操作系统底层功能。 核心思想：借助 Chromium (渲染视图) 和 Node.js (处理操作系统交互) 的能力，Electron 让 Web 技术栈能够构建全功能的跨平台桌面应用。 一、Electron 简介与优势1.1 什么是 Electron？Electron 可以被简单理解为一个微型浏览器套壳，它包含了： Chromium：提供渲染用户界面的能力，这意味着你可以使用 HTML、CSS 和 JavaScript 来构建应用的 UI。 Node.js：提供访问操作系统底层 API 的能力，例如文件系统、网络、进程管理等。 原生 API 集成：Electron 提供了一套 API，...
2024-07-26
TypeScript高级类型
TypeScript 高级类型 提供了强大的工具，允许开发者以更灵活、更精确的方式定义和操作类型。这些高级类型不仅增强了代码的类型安全性，还提升了开发体验，使得复杂的数据结构和业务逻辑能够更清晰地表达和维护。掌握 TypeScript 的这些高级特性，是成为一名高效 TypeScript 开发者的关键。 核心思想：高级类型允许我们基于现有类型进行转换、组合、提取，以及根据不同条件生成新类型，从而构建出更健壮、更具表达力的类型系统。 一、联合类型 (Union Types)联合类型表示一个值可以是多种类型中的任意一种。使用 | 符号连接不同的类型。 1.1 定义与使用1234567891011121314// 定义一个联合类型，表示一个变量可以是 string 或 numbertype StringOrNumber = string | number;let id: StringOrNumber;id = "123"; // OKid = 123; // OK// id = true; // Error: Type 'boolean...
2023-04-17
前端项目工程化详解
随着前端应用的复杂度日益增加，单纯依靠人工管理和协作已经无法满足高效、高质量开发的需求。前端工程化应运而生，它旨在通过将软件工程的思想和方法引入前端开发，构建一套系统化、标准化、自动化、体系化的解决方案，以提高开发效率、保障代码质量、降低维护成本。 前端工程化的核心思想是：以自动化取代人力，以工具取代重复劳动，以规范约束散漫。 一、什么是前端工程化？前端工程化是构建、管理和维护前端项目的实践和工具集。它涵盖了从项目初始化、开发、构建、测试到部署的整个生命周期，目标是提升团队协作效率、统一代码风格、保证项目质量、优化产物性能以及实现快速迭代。 它不仅仅是使用几个构建工具，更是一种体系化的思维方式和工作流。 二、为什么需要前端工程化？在没有工程化的时代，前端开发面临诸多挑战： 开发效率低下：手动重复任务（如文件合并、压缩），环境搭建复杂。 代码质量参差不齐：缺乏统一的代码规范和质量检查机制，导致 Bug 增多，难以维护。 团队协作困难：不同成员的代码风格差异大，冲突频繁，交接成本高。 项目性能不佳：缺乏自动化优化手段（如图片压缩、按需加载），页面加载慢。 部署上线复杂：手动...
2024-10-11
Go Modules(go mod)详解
Go Modules (Go Mod) 是 Go 语言自 Go 1.11 版本引入的官方包管理系统，并在 Go 1.13 版本后成为默认的依赖管理工具。它旨在解决之前 Go 生态系统中依赖管理混乱的问题，提供了一种简洁、可靠且支持版本控制的方式来管理 Go 项目的依赖。 核心思想：将项目代码与依赖项的版本管理解耦，不再强制依赖 $GOPATH，每个模块(项目)在自己的目录中独立管理依赖，并通过 go.mod 文件清晰定义所有直接和间接依赖及其精确版本。 一、为什么需要 Go Modules？在 Go Modules 出现之前，Go 语言的依赖管理主要围绕 $GOPATH 环境变量展开。这种方式存在一些显著问题： 全局 $GOPATH 污染：所有项目都共享 $GOPATH 下的依赖，不同项目对同一个依赖可能需要不同版本，导致版本冲突或需要技巧性地管理 $GOPATH。 非确定性构建：没有明确的依赖版本锁定机制，go get 命令总是获取依赖的最新版本，可能导致构建结果不一致。 对 $GOPATH 的严格依赖：项目必须放置在 $GOPATH/src 目录下，对项目结构造成限...
2024-11-27
Python Setuptools 详解
Setuptools 是一个强大的 Python 库，用于简化 Python 项目的打包 (packaging)、分发 (distribution) 和安装 (installation)。它是 distutils 库的增强版，提供了一系列高级功能，如声明项目元数据、自动发现包、安装依赖项、创建可执行脚本和支持插件机制等。Setuptools 已经成为 Python 项目管理和分发的事实标准 (de facto standard)。 核心思想：将 Python 代码、资源文件、元数据和依赖项封装成标准化的发行包 (Source Distribution 或 Wheel)，方便用户通过 pip 等工具安装和管理，从而实现代码的轻松共享和复用。 一、为什么需要 Setuptools？在 Python 项目开发中，尤其当项目需要被他人使用、共享或部署到不同环境时，会遇到以下问题： 代码复用与分发：如何将自己的 Python 代码模块化，并方便地分享给他人使用？简单地复制粘贴文件显然不是一个可持续的方案。 依赖管理：我的项目依赖了哪些第三方库？如何确保用户在安装我的项目时，这些依...
2023-03-01
React入门教程：快速构建交互式用户界面
React (通常称为 React.js 或 ReactJS) 是一个用于构建用户界面的 JavaScript 库，由 Facebook (现为 Meta) 创建和维护。它允许开发者声明式地创建复杂的、交互式的 UI，其核心思想是组件化和响应式更新。React 专注于视图层，与传统 MVC 模式中的 V (View) 相对应。 核心思想：“声明式地”构建组件化的 UI。开发者描述 UI 在给定状态下的样子，React 负责高效地更新 DOM 以匹配该状态。 重要提示: React 主要使用 TypeScript 或 JavaScript (JSX) 进行开发。本文档中的所有代码示例都将使用 TypeScript (TSX) 语言，以满足类型安全的需求。 一、为什么需要 React？在现代 Web 开发中，构建复杂的用户界面面临诸多挑战： DOM 操作的复杂性与性能瓶颈：直接操作 DOM 繁琐且容易出错，尤其是在数据频繁变化时，手动优化 DOM 更新的性能极其困难。 代码组织与复用性：随着应用规模的增长，UI 代码变得难以管理，组件之间的逻辑耦合高，复用性差。 状态管...