插件系统：Hook 执行、排序与核心插件

Vite 的插件系统是其可扩展性的核心所在——正是依靠它，React、Vue、Svelte 以及数百个社区集成才得以通过统一的接口接入。它在 Rolldown 插件 API 的基础上扩展了 Vite 特有的 hook，实现了一套双层排序机制来精确控制执行顺序，并引入了一个优化层，在过滤条件不匹配时提前跳过 hook 调用。

本文将深入剖析插件接口的设计，理解 Vite 如何将 28 个以上的插件按正确顺序组装成流水线，探索用于避免不必要 hook 调用的过滤器缓存机制，并逐一分析最重要的核心插件。

Plugin 接口与 Vite 特有 Hook

Vite 的 Plugin 接口在 Rolldown 的 RolldownPlugin 基础上，扩展了一批在打包器上下文中并不存在的 hook：

Hook	触发时机	用途
config	解析前	修改用户配置
configResolved	解析后	读取最终配置并保存引用
configEnvironment	每个环境初始化时	修改特定环境的选项
configureServer	服务器创建时	添加中间件、访问服务器实例
configurePreviewServer	预览服务器创建时	与上相同，针对预览模式
hotUpdate	开发时文件变更	自定义 HMR 行为
buildApp	构建编排阶段	控制多环境构建顺序
transformIndexHtml	HTML 处理时	注入脚本、修改 HTML

TypeScript 的集成方式值得关注。Vite 在第 86–89 行使用了声明合并来扩展 Rolldown 的类型：

declare module 'rolldown' {
  export interface MinimalPluginContext extends PluginContextExtension {}
  export interface PluginContextMeta extends PluginContextMetaExtension {}
}

这意味着每个 Rolldown 插件的上下文都会自动获得 this.environment——即当前的 Environment 实例。插件作者无需任何类型转换，就能直接访问 this.environment.config、this.environment.mode 以及其他环境相关数据。

代码中还明确区分了两类插件：app 插件和环境插件。环境插件通过构造函数创建，每个环境初始化时调用一次，但不能定义 config 或 configureServer 等应用级 hook。

插件排序：enforce 与 order

Vite 采用双层排序机制。第一层通过插件的 enforce 字段将用户插件分为三组：'pre'、普通（不设 enforce）和 'post'。第二层则通过每个 hook 上的 order 字段，对同组内的 hook 进行更细粒度的排序。

resolvePlugins 函数负责组装最终的插件流水线：

flowchart LR
    subgraph "Pre Zone"
        A1["optimizedDepsPlugin"]
        A2["watchPackageDataPlugin"]
        A3["preAliasPlugin"]
        A4["aliasPlugin (native or JS)"]
        A5["...user pre plugins"]
    end
    subgraph "Normal Zone"
        B1["modulePreloadPolyfillPlugin"]
        B2["oxcResolvePlugin (2 instances)"]
        B3["htmlInlineProxyPlugin"]
        B4["cssPlugin"]
        B5["oxcPlugin"]
        B6["nativeJsonPlugin"]
        B7["wasmHelperPlugin / webWorkerPlugin"]
        B8["assetPlugin"]
        B9["...user normal plugins"]
    end
    subgraph "Post Zone"
        C1["nativeWasmFallbackPlugin"]
        C2["definePlugin"]
        C3["cssPostPlugin"]
        C4["buildHtmlPlugin"]
        C5["...build plugins"]
        C6["...user post plugins"]
        C7["clientInjectionsPlugin"]
        C8["cssAnalysisPlugin"]
        C9["importAnalysisPlugin"]
    end
    A5 --> B1
    B9 --> C1

getSortedPluginsByHook 函数实现了第二层排序逻辑。每次调用 hook 时，都会根据各插件 hook 的 order 属性重新排序。实现上做了针对性优化——通过追踪插入位置的索引，直接将插件写入结果数组，而非创建三个临时数组：

let pre = 0, normal = 0, post = 0
for (const plugin of plugins) {
  const hook = plugin[hookName]
  if (hook) {
    if (typeof hook === 'object') {
      if (hook.order === 'pre') {
        sortedPlugins.splice(pre++, 0, plugin)
        continue
      }
      if (hook.order === 'post') {
        sortedPlugins.splice(pre + normal + post++, 0, plugin)
        continue
      }
    }
    sortedPlugins.splice(pre + normal++, 0, plugin)
  }
}

提示： 有三个仅在开发模式下存在的插件始终排在最后：clientInjectionsPlugin、cssAnalysisPlugin 和 importAnalysisPlugin。它们必须在所有其他转换完成之后才能运行，因为它们需要分析最终输出，以重写 import 路径并注入 HMR 客户端。

过滤器优化系统

Vite 内置了一套过滤器系统，允许插件声明其 hook 关心哪些文件，从而让插件容器在文件不匹配时完全跳过该 hook 的调用。具体实现位于 pluginFilter.ts。

getCachedFilterForPlugin 函数从插件 hook 中提取过滤器声明，并将其缓存在 WeakMap 中：

flowchart TD
    HOOK["Plugin hook with filter"] --> EXTRACT["extractFilter(hook)"]
    EXTRACT --> CHECK{"Hook type?"}
    CHECK -->|resolveId| IDFilter["createIdFilter(rawFilter)"]
    CHECK -->|load| IDFilter
    CHECK -->|transform| TFilter["createFilterForTransform(id, code, moduleType)"]
    IDFilter --> CACHE["WeakMap<Plugin, FilterValue>"]
    TFilter --> CACHE
    CACHE --> USE["Plugin container checks filter before calling hook"]

对于 transform hook，过滤器可以同时检查模块 ID 和代码内容。这对那些只需处理特定代码模式的插件尤为有用——例如，一个 JSX 转换插件只需要在代码中确实包含 JSX 语法时才运行。

patternToIdFilter 函数同时支持正则表达式和 glob 模式，glob 匹配通过 picomatch 实现。所有路径在匹配前都会统一转换为正斜杠格式。

原生插件与 JS 插件的选择策略

Vite 8 的一个重要设计决策是：尽可能使用原生 Rolldown 插件。查看 resolvePlugins 可以清楚地看到这一模式：

import {
  viteAliasPlugin as nativeAliasPlugin,
  viteJsonPlugin as nativeJsonPlugin,
  viteWasmFallbackPlugin as nativeWasmFallbackPlugin,
  oxcRuntimePlugin,
} from 'rolldown/experimental'

第 60–73 行的 alias 插件选择逻辑展示了具体的回退策略：

isBundled && !config.resolve.alias.some((v) => v.customResolver)
  ? nativeAliasPlugin({ entries: config.resolve.alias.map(/*...*/) })
  : aliasPlugin({ entries: config.resolve.alias, customResolver: viteAliasCustomResolver })

在构建阶段且没有自定义 resolver 时，使用 Rust 编写的原生插件；否则回退到 JS 版本的 @rollup/plugin-alias。这样既保证了常见场景下的最佳性能，又保留了足够的灵活性。

核心插件深度解析

Resolve 插件

oxcResolvePlugin 在 Rolldown 原生 viteResolvePlugin 的基础上封装了 Vite 特有的逻辑。它返回一个插件数组——在开发模式下还会包含 optimizerResolvePlugin——并通过 perEnvironmentOrWorkerPlugin 为每个环境创建专属的原生 resolver。

该 resolver 处理 Vite 的特殊 URL 前缀（/@fs/、/@id/）、browser 字段映射、条件导出、可选 peer 依赖，以及与依赖优化器的集成。其中，finalizeBareSpecifier 回调负责将 import React from 'react' 这样的裸导入重定向到预构建的依赖文件。

Import Analysis 插件

importAnalysisPlugin 是一个仅在开发模式下运行的插件，它会重写模块中的每一条 import 语句。它使用 es-module-lexer 在不构建完整 AST 的情况下解析 import，再借助 MagicString 完成重写。裸导入会被转换为指向优化后依赖的 URL，相对导入会附加时间戳查询参数以实现缓存失效，HMR API（import.meta.hot）也会在此阶段被识别和处理。

CSS 插件

cssPlugin 代码量超过 3500 行，是体量最大的核心插件，负责处理：

• CSS 预处理器（Sass、Less、Stylus），通过可选 peer 依赖接入
• PostCSS 处理，支持自动检测配置文件
• CSS Modules，生成作用域化的类名
• Lightning CSS，作为可替换的处理引擎
• 全流程的 source map 处理
• 开发模式下的内联注入（<style> 标签）与构建模式下的文件提取

该插件被拆分为三个部分：cssPlugin（预处理）、cssPostPlugin（后处理与提取）和 cssAnalysisPlugin（仅开发模式，用于追踪 import）。

下一篇预告

至此，我们已经了解了插件如何排序、过滤，并被组装成一条包含 28 个以上组件的流水线。下一篇文章将聚焦于文件变更时发生的一切：HMR 系统如何在模块图中追踪更新边界、向浏览器发送更新载荷，以及客户端如何重新导入更新后的模块。我们还将深入探讨依赖预构建——Rolldown 如何扫描 import、打包 node_modules，并从缓存中提供服务。