前端工程化 / 系统课时
理解插件执行顺序
理解插件执行顺序
Vite 插件顺序问题通常表现为同一份源码在不同配置下得到不同转换结果。本课用一个可运行的三阶段转换示例,区分 enforce、插件数组顺序与钩子自身的 order,并建立从现象到定位的固定检查路径。
学习目标
- 说明
pre、默认组和post三类插件在整体管线中的位置 - 判断
resolveId、load、transform等钩子的主要执行阶段 - 用日志和中间结果定位插件先后顺序造成的转换差异
先分清两层顺序
enforce 控制插件进入哪一个执行分组,而不是给所有钩子设置一个绝对优先级。Vite 解析后的主要顺序是:别名处理、用户 pre 插件、Vite 核心插件、普通用户插件、Vite 构建插件、用户 post 插件以及构建后处理插件。未设置 enforce 的同组用户插件通常按数组中的先后顺序参与执行。:contentReference[oaicite:0]{index=0}
钩子顺序是另一层规则。模块进入管线时,核心链路通常是 resolveId 确定模块标识,load 提供源码,transform 逐个修改源码;开发服务器会按模块请求重复这条链路。部分钩子还支持自己的 order,例如 transformIndexHtml 的 pre 与 post,它与插件级 enforce 不能混为一谈。:contentReference[oaicite:1]{index=1}

用转换链验证实际顺序
下面故意把插件数组写成 post、默认、pre 的反向顺序。三个插件依次把占位标识转换为 "step-1"、"step-2" 和 "done",终端日志可直接证明真实执行顺序。
import { defineConfig, type Plugin } from 'vite'
function stagePlugin(
name: string,
enforce?: 'pre' | 'post',
): Plugin {
return {
name,
enforce,
transform(code, id) {
if (!id.endsWith('/src/main.ts')) return null
console.log(`[${name}] ${id}`)
if (name === 'step-pre') {
return code.replace('__VALUE__', '"step-1"')
}
if (name === 'step-normal') {
return code.replace('"step-1"', '"step-2"')
}
return code.replace('"step-2"', '"done"')
},
}
}
export default defineConfig({
plugins: [
stagePlugin('step-post', 'post'),
stagePlugin('step-normal'),
stagePlugin('step-pre', 'pre'),
],
})在 src/main.ts 中写入:
console.log(__VALUE__)启动开发服务器:
npm run dev预期输出
[step-pre] <PATH>/src/main.ts
[step-normal] <PATH>/src/main.ts
[step-post] <PATH>/src/main.ts
浏览器控制台:
done<PATH> 是项目绝对路径,实际值因机器而异。开发服务器首次请求模块或发生热更新时,相关日志可能再次出现,这是模块重新进入转换链的正常结果。
定位顺序问题的固定步骤
先确认发生差异的对象:是模块解析、源码加载、代码转换,还是 HTML 注入。随后只保留相关插件,并在目标钩子中同时打印插件名、模块 id 和转换前后的关键标记。
若同组插件顺序不对,先调整数组顺序;若必须跨过 Vite 核心或构建插件,再使用 enforce。只有钩子本身支持 order 时,才在钩子对象上设置顺序。不要用 post 解决所有冲突,因为后执行的插件可能拿到已经失去语义信息的代码。
常见误判
apply: 'build' 或 apply: 'serve' 决定插件是否参与当前命令,不负责排序。某个插件在开发阶段完全没有日志,优先检查 apply,而不是立即修改 enforce。
另一个常见问题是匹配条件过宽。transform 会接触大量模块,包含查询参数、虚拟模块或依赖文件;定位时应限制 id,否则日志顺序会被无关模块淹没,容易把不同模块的调用误认为同一条链路。