插件系统

相关源文件

• docs/guide/cli.md
• packages/vite/client.d.ts
• packages/vite/src/node/__tests__/__snapshots__/utils.spec.ts.snap
• packages/vite/src/node/__tests__/build.spec.ts
• packages/vite/src/node/__tests__/plugins/assetImportMetaUrl.spec.ts
• packages/vite/src/node/__tests__/plugins/css.spec.ts
• packages/vite/src/node/__tests__/plugins/fixtures/css-module-compose/css/bar.module.css
• packages/vite/src/node/__tests__/plugins/json.spec.ts
• packages/vite/src/node/__tests__/plugins/workerImportMetaUrl.spec.ts
• packages/vite/src/node/__tests__/scan.spec.ts
• packages/vite/src/node/__tests__/utils.spec.ts
• packages/vite/src/node/build.ts
• packages/vite/src/node/cli.ts
• packages/vite/src/node/config.ts
• packages/vite/src/node/constants.ts
• packages/vite/src/node/http.ts
• packages/vite/src/node/index.ts
• packages/vite/src/node/logger.ts
• packages/vite/src/node/optimizer/esbuildDepPlugin.ts
• packages/vite/src/node/optimizer/index.ts
• packages/vite/src/node/optimizer/optimizer.ts
• packages/vite/src/node/optimizer/scan.ts
• packages/vite/src/node/plugin.ts
• packages/vite/src/node/plugins/asset.ts
• packages/vite/src/node/plugins/css.ts
• packages/vite/src/node/plugins/html.ts
• packages/vite/src/node/plugins/importAnalysis.ts
• packages/vite/src/node/plugins/importAnalysisBuild.ts
• packages/vite/src/node/plugins/index.ts
• packages/vite/src/node/plugins/json.ts
• packages/vite/src/node/plugins/optimizedDeps.ts
• packages/vite/src/node/plugins/preAlias.ts
• packages/vite/src/node/plugins/resolve.ts
• packages/vite/src/node/preview.ts
• packages/vite/src/node/server/hmr.ts
• packages/vite/src/node/server/index.ts
• packages/vite/src/node/server/middlewares/__tests__/hostCheck.spec.ts
• packages/vite/src/node/server/middlewares/hostCheck.ts
• packages/vite/src/node/server/middlewares/indexHtml.ts
• packages/vite/src/node/server/middlewares/transform.ts
• packages/vite/src/node/server/moduleGraph.ts
• packages/vite/src/node/server/pluginContainer.ts
• packages/vite/src/node/server/transformRequest.ts
• packages/vite/src/node/server/ws.ts
• packages/vite/src/node/utils.ts

本文档涵盖了 Vite 的插件系统架构、内置插件、插件执行流程以及插件开发 API。插件系统是 Vite 最主要的扩展机制，允许自定义构建流程、资源处理和开发服务器行为。

有关配置选项的信息，请参阅 配置系统。有关开发服务器中间件系统的详细信息，请参阅 开发服务器。

核心架构概述

Vite 的插件系统在 Rollup 的插件架构基础上进行了扩展，增加了特定于开发和构建流程的其他钩子和功能。该系统围绕一个插件容器构建，该容器管理不同环境下的插件执行。

插件系统架构

来源： packages/vite/src/node/server/pluginContainer.ts67-123 packages/vite/src/node/plugins/index.ts1-150 packages/vite/src/node/plugin.ts1-400

插件容器和执行

PluginContainer 是插件执行的中央协调器，它实现了 Rollup 的插件 API，同时增加了 Vite 特有的增强功能。

插件容器架构

来源： packages/vite/src/node/server/pluginContainer.ts200-500 packages/vite/src/node/plugin.ts50-150

关键插件容器函数

功能	目的	位置
createPluginContainer	创建插件容器实例	packages/vite/src/node/server/pluginContainer.ts200-250
resolveId	解析模块标识符	packages/vite/src/node/server/pluginContainer.ts400-500
load	加载模块内容	packages/vite/src/node/server/pluginContainer.ts500-600
transform	转换模块代码	packages/vite/src/node/server/pluginContainer.ts600-800
buildStart	初始化构建过程	packages/vite/src/node/server/pluginContainer.ts300-350

内置插件类型

Vite 包含许多内置插件，用于处理不同资源类型和构建场景的核心功能。

核心内置插件

来源： packages/vite/src/node/plugins/index.ts20-150 packages/vite/src/node/plugins/css.ts294-441 packages/vite/src/node/plugins/resolve.ts160-200

按阶段划分的插件类别

类别	阶段	关键插件	目的
预处理	pre	aliasPlugin, preAliasPlugin	模块路径解析
核心处理	normal	cssPlugin, resolvePlugin, htmlInlineProxyPlugin	资源转换
后期处理	post	importAnalysisPlugin, definePlugin	代码分析和注入
特定于构建	build	manifestPlugin, terserPlugin, buildReporterPlugin	生产优化

插件钩子和生命周期

Vite 插件实现了 Rollup 的钩子系统，并增加了特定的开发钩子。

插件钩子执行流程

来源： packages/vite/src/node/plugin.ts100-200 packages/vite/src/node/server/pluginContainer.ts300-800

钩子类型和执行

Hook 类型	执行	用途	示例
first	第一个非空结果	模块解析	resolveId
sequential	按顺序执行所有插件	代码转换	transform
parallel	并行执行所有插件	副作用	buildStart

特定于环境的插件配置

Vite 6.0+ 支持按环境进行插件配置，允许客户端和服务器环境使用不同的插件集。

环境插件解析

来源： packages/vite/src/node/config.ts860-900 packages/vite/src/node/plugins/index.ts80-120

特定于环境的插件配置

perEnvironmentPlugin 函数允许插件针对不同环境进行配置

来源： packages/vite/src/node/build.ts469-475 packages/vite/src/node/plugin.ts350-400

插件开发 API

插件接口结构

来源： packages/vite/src/node/plugin.ts1-100 packages/vite/src/node/server/pluginContainer.ts100-200

关键插件上下文方法

方法	目的	返回类型	用途
resolve	解析模块标识符	Promise<PartialResolvedId>	模块解析
load	加载模块内容	Promise<LoadResult>	模块加载
emitFile	发出构建资源	字符串	资源生成
addWatchFile	将文件添加到监视列表	void	文件监控
getModuleInfo	获取模块元数据	ModuleInfo	模块检查

来源： packages/vite/src/node/server/pluginContainer.ts150-400 packages/vite/src/node/plugin.ts200-300