夜雨聆风Vite插件核心钩子的特性
一、前言
上一篇文章我们介绍了 Vite 特有钩子，那些钩子会被 Rollup/Rolldown 忽略。但是如果我们想有编写插件的能力，还需要了解Vite中的一些通用钩子。
在开发中，Vite开发服务器会创建一个插件容器来调用 Rolldown构建钩子，与Rolldown如出一辙。
下面我们来针对这通用的钩子进行一个学习。
二、通用钩子
在 Vite 插件开发中，Vite在开发服务器模式下会模拟 Rolldown / Rollup 的构建流程，因此你可以使用一套通用的 Rolldown / Rollup 风格钩子来干预构建过程。这些钩子贯穿了从服务器启动、模块请求到服务器关闭的整个生命周期。
2.1、服务器启动阶段钩子
这两个钩子在Vite开发服务器启动时调用，适合进行初始化工作。
2.1.1、options
options 钩子是在Vite解析配置后调用，主要目的是读取或修改构建配置，这是修改构建选项的最后机会。
它主要有两个用途：
检查配置：插件可以检查最终生效的配置是否符合预期。 修改配置：插件可以修改这些配置，从而影响后续的构建行为。
1、参数与返回值
参数：接收当前的构建选项对象，这个对象包含了 Rolldown/Rollup的配置（如果是构建模式）以及Vite特有的配置属性。返回值： 你可以返回 null或undefined，表示不修改配置。你可以返回一个新的配置对象，或者返回一个修改后的对象，这会替换或合并到当前的配置中。
exportdefaultfunctionmyPlugin() {
return {
name: 'vite-plugin-xxx'， // 唯一
options(opts) {
//
}
}
}
2、代码示例
假设我们要开发一个插件，强制将构建的目标浏览器版本修改为较新的版本，或者添加一个全局的别名。
示例1：修改配置（同步方式）
exportdefaultfunctionmodifyOptionsPlugin() {
return {
name: 'modify-options-plugin',
options(opts) {
// opts 是当前的选项对象
console.log("当前构建目标：", opts.target);
// 修改配置：强制设置目标环境
// 注意：在 Vite 中，通常通过 config 钩子修改 vite 特有配置更好，
// 但 options 钩子更底层，可以直接操作 rollup / rolldown 相关的选项。
if (!opts.output) {
opts.output = {};
}
// 假设我们要注入一个自定义的选项供后续钩子使用
opts.customOption = 'some-value';
// 返回修改后的选项对象
return opts;
},
};
}
示例 2：异步修改（异步方式）
options 钩子也支持异步操作。这在需要根据某些外部资源（如读取远程配置文件）来决定构建选项时非常有用。
exportdefaultfunctionasyncOptionsPlugin() {
return {
name: 'async-options-plugin',
async options(opts) {
// 模拟异步获取配置
const remoteConfig = await fetchSomeConfig();
if (remoteConfig.entry) {
// 动态添加入口文件
if (typeof opts.input === 'string') {
opts.input = [opts.input, remoteConfig.entry];
} elseif (Array.isArray(opts.input)) {
opts.input.push(remoteConfig.entry);
}
}
return opts;
}
};
}
2.1.2、buildStart
buildStart 是 Vite 插件生命周期中构建阶段的正式起点，如果说options钩子是在做“出发前的路线规划”，那么buildStart就是“引擎点火”的那一瞬间。
在 Vite 开发服务器启动或执行打包命名时，一旦配置项（options）解析完毕，buildStart就会立即调用。
1、核心作用
buildStart的主要目的是初始化，在这个阶段，构建流程已经确定，但还没有开始处理具体的文件。
它通常用于以下场景：
状态重置：如果你在插件中维护了一些全局变量或缓存（例如存储处理过的文件列表），你需要在这里将它们清空，以确保每次构建都是干净的。 资源预加载/预计算：如果你需要提前读取某些文件系统资源、生成某些代码片段，或者建立数据库连接，可以在这里进行。 日志输出：告诉用户构建已经开始。
2、参数说明
它接收一个参数options，即最终确定的构建配置对象（只读：通常不建议在此修改，修改配置应在options钩子完成）。
异步支持：这是一个异步钩子。你可以使用 async 函数，Vite 会等待里面的异步操作（如数据库连接、文件读取）完成后再继续后续的构建流程。
3、开发模式下的行为
在 Vite 的开发模式中，
buildStart仅在服务器启动时执行一次。 当你在浏览器中刷新页面或修改代码导致热更新时，不会重新出发 buildStart，Vite会复用已经启动的服务器实例。
4、代码示例
示例 1：初始化状态（最常见用法）
假设你的插件需要记录哪些文件被转换过，你需要在每次构建开始前清空这个记录表。
exportdefaultfunctionmyStatePlugin() {
// 定义一个闭包变量来存储状态
let transformedFiles = [];
return {
name: 'my-state-plugin',
// 1. 构建开始时，重置状态
buildStart() {
console.log('🚀 构建开始，正在重置状态...');
transformedFiles = [];
},
// 2. 在 transform 阶段记录文件
transform(code, id) {
transformedFiles.push(id);
return code;
},
// 3. 构建结束时输出结果
buildEnd() {
console.log(`✅ 构建结束，共处理了 ${transformedFiles.length} 个文件`);
}
};
}
示例 2：执行异步初始化
假设你的插件需要读取一个大的 JSON 配置文件或连接外部服务。
exportdefaultfunctionasyncInitPlugin() {
return {
name: 'async-init-plugin',
async buildStart() {
console.log('正在加载远程配置...');
// 模拟异步操作
try {
const response = await fetch('https://api.example.com/config');
const config = await response.json();
console.log('配置加载成功:', config);
// 你可以将 config 存入闭包变量供后续钩子使用
} catch (e) {
// 如果这里抛出错误，整个构建将会失败
this.error('无法加载必要的远程配置！');
}
}
};
}
2.2、模块请求阶段钩子（核心）
这三个钩子是 Vite 开发服务器最核心的部分，每当浏览器请求一个模块（如 .js, .vue, .css 文件）时，它们会按顺序执行。
2.2.1、resolveId
resolveId 绝对是 Vite 插件机制里的“导航员”。如果说buildStart是点火启动，那resolveId就是告诉Vite每一行import语句到底指向哪里。
它是Vite转换模块请求的第一道关卡，每当代码中出现import ... from ...时，Vite 首先就会调用这个钩子来询问：“这个字符串到底代表哪个文件？”
1、核心作用
resolveId 的主要职责是将导入的源字符串解析为唯一的模块 ID（通常是文件的绝对路径）。
它的主要用途包括：
别名替换：比如将 @/components/foo解析为/src/components/foo.vue。虚拟模块：拦截特定的请求（如 virtual:my-module），告诉 Vite 这个模块存在，但实际上它并不对应磁盘上的物理文件。自定义解析逻辑：比如根据特定规则查找文件，或者拦截第三方库的导入。
2、参数详解
该钩子接收两个主要参数：
source（string） 这是 import语句中的原始字符串。例如： import {foo} from './utils.js'中的'./utils.js'。或者： import React from 'react'中的'react'。importer（string | undefined） 这是发起导入的那个文件的绝对路径。 例如，如果 /src/main.js中引入了./utils.js，那么importer就是src/main.js的路径。注意：如果是入口文件（如 index.html或CLI传入的入口）发起的导入，importer可能为undefined。
3、返回值
返回值的处理非常关键，它决定了 Vite 接下来的行动：
返回 null 或 undefined： 含义：“我不处理这个导入，请交给下一个插件或 Vite 的默认解析器处理。” 这是最常见的情况，如果你的插件只关心特定类型的模块，对于其他模块必须返回 null。 返回一个字符串： 含义：这是解析后的模块 ID（通常是绝对路径）。 Vite 会使用这个返回的 ID 作为该模块的唯一标识，并跳过后续其他插件的 resolveId 钩子（除非配置了 enforce: 'post' 等） 返回一个对象： 通常包含 { id: string, external?: boolean, moduleSideEffects?: boolean }。external: true 表示这是一个外部依赖（如 CDN 上的库），不需要打包。
4、执行流程图解
当一个文件A 导入 文件B时：
1、Vite调用 插件1的resolveId('B', 'A的路径')。2、如果 插件1返回 null， Vite调用插件2的resolveId。3、...依次类推。 4、如果所有插件都返回null，Vite使用内置的Node.js解析算法（查找 node_modules）等。5、一旦某个插件返回了具体的路径，解析结束，进入下一个钩子 load。
5、代码示例
示例 1：实现一个简单的别名
这个插件将所有以 ~ 开头的导入解析为 src 目录下的文件。
import { resolve } from'path';
import fs from'fs';
exportdefaultfunctiontildeAliasPlugin() {
return {
name: 'tilde-alias',
resolveId(source, importer) {
// 只处理以 ~ 开头的导入
if (source.startsWith('~')) {
// 假设项目根目录下的 src 文件夹
const projectRoot = process.cwd();
const newPath = resolve(projectRoot, 'src', source.slice(1));
console.log(`解析别名: ${source} -> ${newPath}`);
// 返回绝对路径，Vite 会去加载这个路径
return newPath;
}
// 其他导入不处理
returnnull;
}
};
}
2.2.2、load
如果说 resolveId 是负责导航（确定文件在哪），那么 load 钩子就是负责取货（读取文件内容）。
它是 Vite 插件生命周期中，真正获取模块源代码的第一个机会。
1、核心作用
load 钩子的主要职责是加载模块的内容，当 resolveId 确定了一个模块ID（路径）后，Vite会立即调用 load 钩子来获取该模块的实际代码内容。
它的主要用途包括：
加载虚拟模块：对于在 resolveId 中拦截的虚拟模块（如 virtual:my-module），你需要在这里返回一段生成的代码字符串，因为磁盘上并没有这个文件。 自定义文件读取：如果不使用 Vite 默认的读取方式（例如从数据库、网络或压缩包中读取文件），可以在这里实现。 优化构建性能：如果插件知道某个模块不需要转换，可以直接返回内容，跳过后续的解析步骤。
2、参数与返回值
它接收一个参数：id（string）
这是经过 resolveId解析后的绝对路径（或唯一的模块ID）。
返回值：
返回 null 或 undefined 含义：“我不处理这个文件，请 Vite 使用默认方式读取磁盘上的文件内容。” 行为：Vite 会继续执行后续流程，通常是从磁盘读取文件内容。 返回字符串 (String)： 含义：“这是我提供的源代码。” 行为：Vite 将使用这个字符串作为该模块的内容，并将其传递给下一个钩子 transform。
3、代码示例
示例 1：实现虚拟模块
这是 load 钩子最经典的应用场景。结合之前的 resolveId，我们可以创建一个完全在内存中存在的模块。
exportdefaultfunctionvirtualModulePlugin() {
return {
name: 'virtual-module-plugin',
// 1. 拦截虚拟 ID
resolveId(id) {
if (id === 'virtual:my-module') {
return id; // 返回 ID 表示“我处理这个”
}
returnnull;
},
// 2. 提供虚拟模块的内容
load(id) {
if (id === 'virtual:my-module') {
// 返回一段 JS 代码字符串
return'export const msg = "Hello from a virtual module!";';
}
returnnull; // 其他文件交给默认处理
}
}
}
2.2.3、transform
transform 钩子是 Vite 插件系统中处理代码转换的核心环境，负责对模块源码进行实际修改，它是Vite实现 TypeScript编译、CSS预处理、代码注入等能力的关键机制。所有插件的transform钩子会按顺序串行执行，前一个插件的输出作为后一个插件的输入，最终结果决定浏览器实际运行的代码。
1、核心作用
修改模块源码：对 load 钩子返回的原始代码进行转换（如 TS → JS、Vue SFC 编译、JSX 转译等）。 实现细粒度扩展：通过插件链式处理，不同插件可专注处理特定类型的文件（如 TS 插件只处理 .ts 文件，CSS 插件只处理 .scss 文件）。 支持热更新：转换后的代码会直接返回给开发服务器，无需完整重建。
2、执行流程
1、触发条件：当模块请求命中 isJSRequest 或 isCSSRequest 等条件时触发 2、串行处理： 插件按配置顺序依次执行 transform 钩子。 前一个插件的返回值会作为 code 参数传递给下一个插件。 若插件返回 null，则跳过该插件的处理，保留当前 code。 3、最终输出：所有插件处理完成后，将最终 code 返回给浏览器。
3、参数与返回值
参数说明：
transform(
code: string, // 当前模块的源码（初始值来自 load 钩子）
id: string, // 模块的唯一标识（绝对路径或虚拟 ID）
options?: { ssr: boolean } // 额外选项（如 SSR 模式标识）
)
返回值规则：
返回字符串：覆盖当前 code，作为输入传递给下一个插件。返回 null / undefined：跳过当前插件的转换，保留 code传递给下一个插件。返回 { code, map }：返回转换后的代码及SourceMap（用于调试）
4、代码示例
示例1： 日志输出与条件转换
exportdefault {
name: 'log-transform',
transform(code, id) {
// 仅处理 .js 文件
if (!id.endsWith('.js')) returnnull;
console.log(`正在转换模块: ${id}`);
// 在代码开头注入日志
const injectedCode = `console.log("Loaded: ${id}");\n${code}`;
return injectedCode;
}
};
2.3、服务器关闭阶段钩子
这两个钩子在 Vite 开发服务器关闭或构建结束时调用，用于清理工作。
2.3.1、buildEnd
buildEnd 是 Vite 插件系统重标志构建逻辑结束的关键钩子，仅在生产构建完成时触发，它表示所有模块的解析、转换和代码生成流程已结束，但文件尚未写入磁盘，其核心作用是执行构建收尾操作，如资源清理、统计分析或错误处理。无法再修改最终输出内容。
1、参数与错误处理
buildEnd(err?: Error): void
err参数：若构建过程中发生错误，会传递 Error 对象；若构建成功，err 为 undefined。 错误捕获：可在此钩子中统一处理构建失败逻辑（如发送告警、清理临时文件）。
2、典型应用场景
示例1：构建统计与日志
耗时分析：记录从 buildStart 到 buildEnd 的总耗时。 模块统计：输出参与构建的模块数量、类型分布等信息。
let startTime;
exportdefault {
name: 'build-stats',
buildStart() {
startTime = Date.now();
},
buildEnd(err) {
if (err) {
console.error(`构建失败: ${err.message}`);
} else {
const duration = Date.now() - startTime;
console.log(`✅ 构建成功，耗时: ${duration}ms`);
}
}
};
示例2：资源清理
释放内存缓存：清除插件内部维护的临时数据结构。 关闭外部连接：断开数据库、网络服务等资源占用。
exportdefault {
name: 'resource-cleaner',
buildEnd() {
// 清理插件内部缓存的模块依赖图
this.moduleGraph.clear();
// 关闭自定义的数据库连接
if (this.db) this.db.close();
}
};
示例3：错误处理与告警
构建失败通知：通过邮件、Webhook 等方式发送告警。 回滚操作：触发失败时的资源回滚逻辑。
exportdefault {
name: 'build-alert',
buildEnd(err) {
if (err) {
// 发送构建失败通知
sendSlackAlert(`构建失败: ${err.message}`);
// 触发回滚
triggerRollback();
}
}
};
2.3.2、closeBundle
closeBundle 是 Vite 插件系统中标志构建流程彻底结束的最终钩子，仅在所有输出文件已写入磁盘后触发。它表示构建流程完全完成，是执行最终清理、资源发布或后置操作的唯一安全时机。开发环境仅在服务器关闭时触发一次，生产环境在每次构建完成后触发。其核心价值在于：此时可安全操作磁盘上的完整产物文件，且不会干扰 Vite 的构建流程。
1、触发时机
生产环境（vite build）： 所有文件写入 dist 目录后立即触发（writeBundle 之后）。 开发环境（vite serve）： 仅在服务关闭时触发一次（如手动终止进程或热重启），开发过程中不会重复触发。
2、典型应用场景
示例1：生成额外文件（最常用）
版本信息写入：创建 version.json 记录构建时间、依赖版本等元数据。
exportdefault {
name: 'version-plugin',
apply: 'build',
closeBundle() {
const versionInfo = {
version: "1.0.0",
buildTime: newDate().toISOString()
};
fs.writeFileSync('dist/version.json', JSON.stringify(versionInfo, null, 2));
}
};
注意：若在 buildEnd 或 generateBundle 中写入，文件可能被 Vite 后续操作覆盖。
