夜雨聆风Vite插件学习指南：从概念到实战
一、什么是Vite插件
Vite 插件是 Vite 构建工具的核心扩展机制，它允许开发者通过编写 JavaScript 对象来拦截和定制 Vite 的构建流程，实现各种自定义功能。插件可以访问 Vite 在不同构建阶段的生命周期钩子，执行特定逻辑，从而扩展 Vite 的能力。例如，修改配置、转换源代码、优化资源、生成文件等。
Rolldown的插件接口几乎完全兼容Rollup的插件接口，因此，如果您之前编写过Rollup插件，您就已经知道如何编写Rolldown插件了！
二、Vite 插件的作用
1.扩展功能：通过插件添加 Vite 本身不具备的功能，如代码压缩、环境变量注入、自动导入组件等。 2.优化构建流程：在构建的不同阶段（如解析配置、转换模块、打包输出）插入自定义逻辑，提升效率或优化输出结果。 3.定制开发体验：例如，在开发服务器启动时打印欢迎信息，或在构建完成后显示统计信息。 4.集成第三方工具：将现有工具（如 ESLint、Babel）整合到 Vite 工作流程中。 5.团队内部工具标准化：通过插件封装团队通用的构建逻辑，提升协作效率。
三、插件约定
Vite 8 要求开发者根据插件的实际功能边界选择命名规范：
若插件仅依赖Rollup兼容的钩子（不依赖Vite特有功能），应遵循 Rolldown 插件规范，以实现跨工具链复用（Vite/Rolldown/Rollup）。 若插件必须使用Vite特有钩子（如开发服务器逻辑），则需遵循Vite专属插件规范，明确其生态边界。这一规范旨在 解决双引擎时代插件分裂问题，推动插件生态从“开发/生产环境分离”转向“统一工具链复用”。
3.1、兼容Rolldown的插件（推荐优先采用）
适用于：
仅使用 Rollup 标准插件 API（如 transform、buildStart 等钩子），不依赖 Vite 特有功能（如开发服务器、HMR 逻辑）的插件。 例如：代码压缩、静态资源处理、通用打包优化类插件。
规范要求：
命名前缀：必须以 rolldown-plugin-开头（如rolldown-plugin-visualiuzer）。关键词声明：package.json 中需包含 rolldown-plugin和vite-plugin关键字。生态价值： 可直接用于 Vite8、Rolldown或Rollup项目，无需额外适配。避免双引擎时代“开发/生产插件不一致”的问题，实现“写一次，多端运行”。
3.2、Vite专属插件
适用于：
必须依赖 Vite 特有功能的插件（如操作开发服务器、HMR 逻辑、config 阶段的 Vite 专属配置）。 例如：框架集成插件（vite-plugin-vue）、开发环境调试工具。
规范要求：
命名前缀：必须以 vite-plugin-开头（如 vite-plugin-react）。关键词声明：package.json 中需包含 vite-plugin 关键字。
3.3、框架特定插件的细化规则
若插件仅服务于某一框架，需在命名中进一步明确框架类型：
Vue 插件：前缀 vite-plugin-vue-（如 vite-plugin-vue-router）。React 插件：前缀 vite-plugin-react-（如 vite-plugin-react-svgr）。Svelte 插件：前缀 vite-plugin-svelte-。
四、Vite钩子执行阶段
Vite8 通过 Rolldown 统一引擎实现了开发与生产环境的流程一致性，但开发模式（vite dev）与生产构建（vite build）仍存在关键差异。核心区别在于：开发模式仅执行模块解析与转换的最小流程，跳过所有与打包产物生成相关的阶段。下面我们按执行阶段来详细解析：
4.1、配置解析阶段（仅执行一次）
此阶段在服务器启动前完成，用于处理Vite配置文件（vite.config.ts）。
4.1.1、config
config 钩子是在解析 Vite 配置前被调用的核心插件钩子，主要用于修改原始用户配置，它接收用户配置对象和环境变量，可通过返回部分配置或直接修改配置实现动态调整，但无法在该钩子中注入新插件。
调用时机：在Vite解析用户配置文件（如 vite.config.ts）之前触发。核心作用：允许插件动态修改Vite的原始配置，例如调整路径别名、环境变量或构建选项等。
1、参数说明
exportdefaultfunctionmyPlugin() {
return {
name: 'vite-plugin-xxx', // 唯一
config(config, { command, mode }) {
//...
}
}
}
config: UserConfig用户配置文件或命令行传入的原始配置对象（未解析的初始状态） env: { mode: string, command: string }环境上下文mode：当前模式（如 development、production）command：执行的命令（ serve开发服务器/build生产构建）
2、返回值处理方式
返回值处理方式主要分为两种，一种是返回部分配置对象（推荐），另一种是直接修改config参数。
2.1、返回部分配置对象（推荐）
返回的对象会通过深度合并到现有配置中，避免直接修改原始对象导致的副作用。
示例：动态修改端口配置
我们在项目的根目录下新建一个plugins目录，用来自定义插件，然后在该目录下新建vite-plugin-auto-port.ts文件。然后将编写好的插件在vite.config.ts中进行引用。
// vite-plugin-auto-port.ts
exportdefaultfunctionautoPort() {
return {
name: 'vite-plugin-auto-port',
config(config, { command }) {
// 开发模式下动态分配端口（避免冲突）
// 直接返回port，避免修改原始配置
if(command === 'serve') {
let port = 5000 + Math.floor(Math.random() * 1000);
config.server.port = port
console.log(`[Vite] 动态分配端口: ${port}`);
return {
port: port
}
}
},
}
}
2.2、直接修改config参数（不推荐）
这个仅在深度合并无法满足需求时使用：
// vite-plugin-auto-port.ts
exportdefaultfunctionautoPort() {
return {
name: 'vite-plugin-auto-port',
config(config, { command }) {
// 开发模式下动态分配端口（避免冲突）
// 修改原始配置
if(command === 'serve') {
let port = 5000 + Math.floor(Math.random() * 1000);
config.server.port = port
console.log(`[Vite] 动态分配端口: ${port}`);
}
},
}
}
注意：直接修改可能导致配置冲突，优先选择返回部分配置。
3、适用模式
vite dev） | vite build） | |
|---|---|---|
4.1.2、configResolved
configResolved 钩子是 Vite解析配置完成后触发的核心插件钩子，用户安全读取最终合并的配置对象（ResolvedConfig），它不可用于修改配置，但可存储配置供其他钩子使用，是插件中访问完整配置的唯一可靠时机。
调用时机：在Vite完成所有配置合并（用户配置、命令行参数、插件 config钩子修改等）之后触发。核心作用： 安全读取最终配置：此时配置已完全确定，所有别名（alias）、路径等已合并完成。 存储配置供后续使用：将resolvedConfig保存到闭包中，供其他钩子（如transform、configureServer）调用。 验证配置合法性：检查必要参数是否存在（如base路径是否符合预期）。
1、参数说明
exportdefaultfunctionmyPlugin() {
return {
name: 'vite-plugin-xxx', // 唯一
configResolved(resolvedConfig) {
//...
}
}
}
resolvedConfig：ResolvedConfig：深度合并后的最终配置对象，包含：用户配置（ vite.config.ts）命令行参数覆盖值 插件config钩子的修改结果
2、适用模式
vite dev） | vite build） | |
|---|---|---|
3、典型使用场景
3.1、跨钩子共享最终配置
在插件中存储resolvedConfig，供其他钩子使用：
const examplePlugin = () => {
let config; // 用于存储最终配置
return {
name: 'config-resolved-demo',
configResolved(resolvedConfig) {
config = resolvedConfig; // 存储配置
},
transform(code, id) {
if (config.command === 'serve') {
// 开发环境逻辑
} else {
// 构建环境逻辑
}
}
};
};
3.2、基于命令类型差异化逻辑
根据command值执行不同操作：
configResolved(resolvedConfig) {
if (resolvedConfig.command === 'build') {
// 初始化构建专用资源（如代码分析器）
this.analyzer = new BundleAnalyzer();
} else {
// 开发环境专用逻辑（如启动监控服务）
this.devServer = createDevServer();
}
}
3.3、配置验证与错误处理
检查关键配置是否符合预期：
configResolved(resolvedConfig) {
if (resolvedConfig.base && !resolvedConfig.base.startsWith('/')) {
// 强制base路径以/开头
thrownewError(
**`base路径必须以'/'开头，当前值: ${resolvedConfig.base}`**
);
}
}
注意事项：
configResolved是只读钩子，修改resolvedCOnfig不会生效，且可能破坏Vite内部逻辑，若需修改配置，必须在config钩子中完成。
4.2、开发服务器阶段钩子（仅开发模式生效）
4.2.1、configureServer
configureServer 是 Vite 插件系统中专门用于开发服务器配置的核心钩子，仅在开发模式（vite dev）下生效。
核心作用：在开发服务器启动过程中，通过操作ViteDevServer实例，动态扩展服务器功能（如添加中间件、自定义路由等）
类型： (server: ViteDevServer) => void | (() => void | Promise<void>执行阶段： 在 configResolved钩子之后、服务器开始监听端口之前触发。所有插件的 configureServer钩子执行完毕后，Vite才会启动HTTP服务器。
1、典型使用场景
1.1、添加自定义中间件（拦截请求）
你可以直接在 configureServer 中向 server.middlewares 注入中间件，处理自定义的 API 请求或静态资源映射。
const myPlugin = () => ({
name: 'custom-server-middleware',
configureServer(server) {
// 在 Vite 内置中间件之前执行
server.middlewares.use((req, res, next) => {
if (req.url?.startsWith('/api/mock')) {
res.setHeader('Content-Type', 'application/json')
res.end(JSON.stringify({ message: 'Mock API Response' }))
} else {
next() // 将请求交给下一个中间件处理
}
})
}
})
最经典的场景：
// 自定义一个带有中间件的 Vite 插件
functioncustomMiddlewarePlugin() {
return {
name: 'vite-plugin-custom-middleware',
configureServer(server) {
// 向 Vite 开发服务器添加自定义中间件
server.middlewares.use((req, res, next) => {
const startTime = Date.now()
const { method, url } = req
// 场景一：Mock 模拟数据接口
// 拦截前端发往 /api/mock/user 的请求，直接返回模拟的 JSON 数据
if (url?.startsWith('/api/mock/user')) {
const mockData = {
code: 200,
data: { id: 1, name: '张三', role: '管理员' },
message: '获取用户信息成功（Mock数据）'
}
res.setHeader('Content-Type', 'application/json')
res.statusCode = 200
// 结束响应，不再往下传递
return res.end(JSON.stringify(mockData, null, 2))
}
// 场景二：请求日志记录
// 监听响应结束事件，计算接口耗时并打印日志
const originalEnd = res.end
res.end = function (...args: any[]) {
const duration = Date.now() - startTime
console.log(`[开发服务器日志] ${method}${url} -> 状态码: ${res.statusCode} | 耗时: ${duration}ms`)
// 调用原始的 res.end 方法，确保响应能正常返回给浏览器
return originalEnd.apply(res, args)
}
// 调用 next()，将未被拦截的请求交给 Vite 的下一个中间件处理
next()
})
}
}
}
1.2、 注入后置中间件（在内置中间件之后执行）
如果你希望自定义的中间件在 Vite 处理完静态资源、HTML 转换等内置逻辑之后再运行，可以从 configureServer 中返回一个函数。
const myPlugin = () => ({
name: 'post-server-middleware',
configureServer(server) {
// 返回一个后置钩子，会在 Vite 内部中间件安装后被调用
return() => {
server.middlewares.use((req, res, next) => {
console.log(`请求已处理: ${req.method}${req.url}`)
next()
})
}
}
})
1.3、存储服务器实例并联动其他钩子
将开发服务器实例保存下来，可以在 transform 等钩子中利用它提供的能力（例如通过 WebSocket 向前端发送自定义消息）
const myPlugin = () => {
let devServer
return {
name: 'store-server-instance',
configureServer(server) {
devServer = server // 存储服务器实例
},
transform(code, id) {
if (devServer && id.endsWith('.vue')) {
// 在转换 Vue 文件时，通过 WebSocket 发送自定义事件
devServer.ws.send({
type: 'custom',
event: 'vue-file-transformed',
data: { id }
})
}
return code
}
}
}
4.2.2、transformIndexHtml
transformIndexHtml 用于在开发服务器启动和构建过程中动态修改HTML内容。它能在不直接修改原始index.html文件的前提下，实现标题替换、资源注入、预加载优化等操作，核心价值在于解耦HTML模块与动态逻辑。
1、参数说明
functionmyPlugin() {
name: 'vite-plugin-xxx', // 唯一
transformIndexHtml(html, { path, filename, server, bundle}) [}
}
html：当前处理的HTML原始字符串。 ctx：转换上下文对象，包含： path：请求路径（开发模式）或输出路径（构建模式）。 filename：HTML文件的绝对路径。 server：开发服务器实例（仅开发模式）。 bundle：Rollup输出的资源包（仅构建模式）。
执行时机：
开发模式：每次浏览器请求HTML时触发（如刷新页面）。 构建模式：在Rolldown生成最终HTML文件前触发。
2、返回值类型
钩子可返回以下任一形式：
字符串：直接替换原始HTML内容。 标签描述符数组：动态注入新标签（如 <script>、<link>）。{html, tags}对象：同时修改HTML内容并注入标签。
标签描述符结构示例：
{
tag: 'script', // 标签名
attrs: { src: '/main.js' }, // 标签属性
children: '...', // 子内容（可选）
injectTo: 'body'// 注入位置：'head' | 'body' | 'head-prepend' | 'body-prepend'
}
3、示例场景
示例1：动态注入 CDN 脚本（生产环境常用）
在构建时自动将 Vue 依赖替换为 CDN 链接，减少打包体积：
// vite.config.js
exportdefault {
plugins: [
{
name: 'vite-plugin-inject-cdn',
transformIndexHtml(html) {
// 仅在生产构建时注入
if (process.env.NODE_ENV === 'production') {
return {
html,
tags: [
// 将 Vue 从本地 bundle 替换为 CDN
{
tag: 'script',
attrs: {
src: 'https://unpkg.com/vue@3.4.27/dist/vue.global.prod.js',
integrity: 'sha384-...', // 强烈建议添加完整性校验
crossorigin: 'anonymous'
},
injectTo: 'head-prepend'// 确保在业务脚本前加载
},
// 注入自定义初始化逻辑
{
tag: 'script',
children: `console.log("Vue loaded from CDN!");`,
injectTo: 'body'
}
]
};
}
return html;
}
}
]
};
使用 injectTo: 'head-prepend'确保CDN脚本在业务代码前执行。通过 integrity属性防止资源被篡改，提升安全性。
示例 2：构建时 HTML 压缩（提升性能）
移除 HTML 中的注释、换行和多余空格：
// vite.config.js
import { minify } from'html-minifier-terser';
exportdefault {
plugins: [
{
name: 'vite-plugin-html-compress',
transformIndexHtml: {
enforce: 'post', // 确保在其他 HTML 处理钩子后执行
async transform(html, ctx) {
if (ctx.bundle) { // 仅生产构建时压缩
return minify(html, {
collapseWhitespace: true,
removeComments: true,
minifyCSS: true
});
}
return html;
}
}
}
]
};
通过 enforce: 'post'确保在 Vite 默认 HTML 处理完成后执行。
4.2.4、handleHotUpdate
handleHotUpdate 是 Vite插件系统中处理热更新逻辑的核心钩子，用于在文件变更后自定义模块更新行为，它通过精准控制热更新边界（哪些模块需要更新）、过滤无关变更、注入自定义逻辑，显著提升开发体验，其核心价值在于：避免不必要的全量刷新，保留应用状态，实现局部精准更新。
1、参数说明
钩子接收一个上下文对象ctx，包含以下关键属性：
file：触发变更的文件绝对路径（如 /project/src/components/Button.vue）。 server：开发服务器实例，可访问 server.ws（WebSocket 服务）和 server.moduleGraph（模块依赖图）。 modules：与变更文件关联的模块对象数组（一个文件可能对应多个模块，如 .vue 文件拆分为 JS 和 CSS 模块）。 read：异步函数，用于重新读取变更后的文件内容（常用于内容对比）。
2、执行流程
1、文件变更检测：Vite 通过 chokidar 监听文件系统，捕获修改事件。 2、依赖分析：基于 moduleGraph 计算变更文件影响的模块范围。 3、钩子调用：按插件注册顺序依次执行所有插件的 handleHotUpdate，允许插件修改更新逻辑。 4、边界确认：若插件返回模块列表，则跳过内置逻辑；否则 Vite 通过 propagateUpdate 自动推导热更新边界。 5、通知客户端：将最终需更新的模块通过 WebSocket 推送给浏览器。
3、典型使用场景
示例 1：仅更新 CSS 变更（Vue 单文件组件优化）
当 .vue 文件仅样式修改时，跳过 JS 模块更新，实现 CSS 热重载无刷新：
// vite.config.js
exportdefault {
plugins: [
{
name: 'css-only-hmr',
async handleHotUpdate(ctx) {
// 仅处理 .vue 文件
if (ctx.file.endsWith('.vue')) {
const prevContent = await ctx.read(); // 变更前内容
const nextContent = await fs.promises.readFile(ctx.file, 'utf-8'); // 变更后内容
// 检测是否仅 CSS 部分变化
const isCssOnlyChanged = isOnlyStyleChanged(prevContent, nextContent);
if (isCssOnlyChanged) {
// **仅返回 CSS 模块**，过滤 JS 模块
return ctx.modules.filter(m => m.url.endsWith('.css'));
}
}
// 默认逻辑：返回所有关联模块
return ctx.modules;
}
}
]
};
// 辅助函数：检查是否仅样式变化
functionisOnlyStyleChanged(prev, next) {
const extractStyle = (content) => content.match(/<style[^>]*>([\s\S]*?)<\/style>/)?. || '';
return extractStyle(prev) !== extractStyle(next) &&
prev.replace(/<style[^>]*>[\s\S]*?<\/style>/, '') ===
next.replace(/<style[^>]*>[\s\S]*?<\/style>/, '');
}
通过 ctx.read() 获取变更前内容，与当前文件内容对比，返回过滤后的 modules 数组，确保 Vite 仅通知 CSS 模块更新，避免 JS 逻辑重执行导致状态丢失。
