Vite 核心架构与使用指南：从 Dev Server、Rolldown 构建到插件体系全解析

本文基于 Vite 官方仓库（当前核心包版本 8.2.2）的 README 及仓库源码展开，系统讲解 Vite 的定位与核心设计（基于原生 ESM 的即时启动 Dev Server、极速 HMR、Rolldown 构建、通用插件接口与全类型化 API），并结合 packages/vite/src/node/cli.ts 中的真实 CLI 实现、packages/vite/package.json 中的依赖与版本事实，以及 docs/guide/features.md 等配套文档，帮助读者在掌握 Vite 完整能力地图的同时，能直接上手开发、构建与插件二次开发。

一、Vite 是什么：下一代前端工具链

Vite（法语"快"的意思，发音近似 "veet"，仓库在 docs/public/vite.mp3 中提供了发音音频）是一个旨在为现代 Web 项目提供更快速、更精简开发体验的构建工具。仓库 README 将其概括为 "Next Generation Frontend Tooling"，并给出六个核心卖点：

• Instant Server Start：开发服务器即时启动，无需等待全量打包；
• Lightning Fast HMR：闪电级的热模块替换（HMR）；
• Rich Features：开箱即用的丰富功能（TypeScript、JSX、CSS 预处理器、静态资产、Web Workers、WebAssembly 等）；
• Optimized Build：面向生产环境的优化构建；
• Universal Plugin Interface：通用的插件接口；
• Fully Typed APIs：全类型化的 API。

从架构上看，Vite 由两个主要部分构成：

1. Dev Server（开发服务器）：在浏览器原生 ES Modules 之上提供大量功能增强，例如极快的热模块替换（HMR）。源码入口位于 packages/vite/src/node/server，CLI 通过 createServer 启动，见 packages/vite/src/node/cli.ts；
2. Build（构建命令）：使用 Rolldown 完成代码打包（注意：仓库 README 明确写有该外部链接对应的 Rolldown 项目），预先配置好以输出高度优化的生产静态资源。仓库中 rolldown 既是 packages/vite/package.json 中约 ~1.2.6 的运行时依赖，也通过 packages/vite/rolldown.config.ts 构建 Vite 自身。

此外，Vite 通过其 Plugin API（对应 docs/guide/api-plugin.md）和 JavaScript API（对应 docs/guide/api-javascript.md）高度可扩展，并提供完整的 TypeScript 类型支持——类型声明位于 packages/vite/types，客户端类型定义见 packages/vite/client.d.ts。

二、版本、运行环境与仓库结构

2.1 Node.js 版本要求

以当前仓库为准，Vite 对运行环境的要求是：

{
  "engines": {
    "node": "^20.19.0 || >=22.12.0"
  }
}

该约束同时出现在根 package.json 与 packages/vite/package.json 中，且 @vitejs/plugin-legacy（packages/plugin-legacy/package.json）与 create-vite（packages/create-vite/package.json）保持同一引擎约束。也就是说，使用本仓库代码时，Node.js 需满足 >=20.19.0（20.x 高版本）或 >=22.12.0。

2.2 仓库中的包矩阵

README 的 Packages 一节列出了仓库内三个主要包，结合各包 package.json 可确认当前版本：

包	位置	当前仓库版本	说明
vite	packages/vite	8.2.2（见 packages/vite/package.json）	核心工具：Dev Server + Build + 类型化 API
@vitejs/plugin-legacy	packages/plugin-legacy	8.2.3（见 packages/plugin-legacy/package.json）	为旧版浏览器构建 legacy 产物
create-vite	packages/create-vite	9.2.0（见 packages/create-vite/package.json）	项目脚手架 CLI，提供各框架模板

整体仓库是一个 pnpm monorepo（pnpm-workspace.yaml），根 package.json 声明 "packageManager": "pnpm@10.34.5"，且 preinstall 脚本通过 npx only-allow pnpm 强制使用 pnpm 安装。仓库还包含 playground 目录（大量端到端测试用例）与 docs 文档站点。

三、Dev Server：基于原生 ESM 的即时启动

3.1 为什么启动快：按需编译

Vite 的 Dev Server 直接依赖浏览器对原生 ES Modules 的支持：源码以 ESM 形式被浏览器按需请求，服务器仅在请求到达时才转换对应模块（配合 Oxc Transformer 做转译），因此冷启动几乎不受模块数量影响。这一点在 docs/guide/features.md 中有系统性描述。

对浏览器原生 ESM 不友好的能力，Vite 做了针对性增强，最典型的是 npm 依赖解析与预打包（Pre-bundling）：

1. 原生 ESM 不支持 import { someMethod } from 'my-dep' 这类裸模块导入。Vite 会检测所有被服务源码中的裸导入，并用 Rolldown 对其进行预打包（Pre-bundle），将 CommonJS/UMD 模块转换为 ESM，这一步使 Vite 的冷启动显著快于基于 JavaScript 的打包器；
2. 随后把导入重写为类似 /node_modules/.vite/deps/my-dep.js?v=xxxx 的有效 URL，浏览器才能正确加载。

需要强调的一点（来自 features 文档）：依赖请求通过 HTTP 头强缓存，若想本地编辑/调试依赖，需要按 docs/guide/dep-pre-bundling.md 中的 "browser cache" 步骤操作。

3.2 极速 HMR

Vite 在原生 ESM 之上提供了 HMR API（docs/guide/api-hmr.md），框架可利用它实现即时、精确的更新，无需刷新页面或销毁应用状态。Vue SFC 与 React Fast Refresh 有官方 HMR 集成插件（vitejs 组织维护），Preact 有官方 @prefresh/vite 集成。通过 create-vite 创建项目时，所选模板已经预配置好这些能力，无需手动设置。HMR 相关的真实行为可在 playground/hmr 与 playground/hmr-ssr 的端到端测试中看到覆盖（如 accept-exports、circular、invalidation 等场景）。

TypeScript 方面，features 文档指出 Vite 使用 Oxc Transformer 将 TypeScript 转译为 JavaScript，HMR 更新可在浏览器中快速反映；且 Vite 只做转译、不做类型检查，官方建议生产构建时额外运行 tsc --noEmit，开发时可用 tsc --noEmit --watch 或 vite-plugin-checker。tsconfig.json 中 isolatedModules、useDefineForClassFields、paths 等选项的处理规则详见 docs/guide/features.md 的 TypeScript 章节。

四、CLI 命令详解（源自 cli.ts 的真实实现）

Vite 的 CLI 定义在 packages/vite/src/node/cli.ts，可执行入口为 bin/vite（packages/vite/package.json 中 bin 字段声明）。当前实现包含以下命令：

4.1 vite / vite dev / vite serve：启动 Dev Server

默认命令为 [root]（见 cli.ts），别名 serve 与 dev：

选项	说明
--host [host]	指定主机名
--port <port>	指定端口
--open [path]	启动时打开浏览器
--cors	启用 CORS
--strictPort	端口被占用时直接退出
--force	强制优化器忽略缓存并重新预打包
--experimentalBundle	使用实验性全量 bundle 模式（官方注释标注 highly experimental）

命令 action 内部动态 import('./server') 获取 createServer，传入 root、base、mode、configFile 等内联配置后调用 server.listen() 并打印 URL；启动时会输出 VITE v<version> 与 ready in <n> ms 的耗时（cli.ts）。此外还支持 --profile 相关快捷键（按 p 启停 Node inspector profiler，cli.ts）。

4.2 vite build：生产构建

build [root] 命令（cli.ts）选项如下：

选项	说明
--target <target>	转译目标，默认 baseline-widely-available
--outDir <dir>	输出目录，默认 dist
--assetsDir <dir>	outDir 下放置资产的目录，默认 assets
--assetsInlineLimit <number>	静态资产 base64 内联阈值（字节），默认 4096
--ssr [entry]	为 SSR 构建指定入口
--sourcemap [output]	输出 sourcemap（false | inline | hidden），默认 false
--minify [minifier]	启用/禁用压缩或指定压缩器：oxc | terser | esbuild，默认 oxc
--manifest [name]	输出构建 manifest json
--ssrManifest [name]	输出 SSR manifest json
--emptyOutDir	当 outDir 在 root 之外时强制清空
-w, --watch	模块变更时重新构建
--app	等价于 builder: {}

从 action 实现（cli.ts）可以看到：vite build 通过 createBuilder(inlineConfig) 创建 builder，依次执行 buildApp() 与 runDevTools()，这说明当前构建入口已经统一到 Rolldown 的 builder 模型之上（--app 选项即 builder: {} 的语法糖）。完整构建配置项参考 docs/config 目录（如 docs/config/build-options.md 等）。

4.3 vite preview 与已废弃的 vite optimize

• preview [root]：本地预览生产构建，支持 --host、--port、--strictPort、--open [path]、--outDir <dir>（默认 dist），实现位于 packages/vite/src/node/preview.ts（cli.ts）；
• optimize [root]：命令帮助文本已明确标注 deprecated——"the pre-bundle process runs automatically and does not need to be called"，即预打包过程现在自动运行，无需手动调用（cli.ts）。

所有命令共享全局选项（--config、--mode、--base、--logLevel、--clearScreen 等，由 GlobalCLIOptions 类型约束），完整 CLI 参考见 docs/guide/cli.md。

五、构建时能力：生产优化与静态资产

features 文档的 Build Optimizations 章节列出了构建过程中自动应用的优化，无需显式配置（除非要禁用）：

• CSS Code Splitting：异步 chunk 使用的 CSS 会被自动抽取为独立文件，并通过 <link> 在对应 chunk 加载时载入，保证 CSS 先加载、chunk 后求值以避免 FOUC；可将 build.cssCodeSplit 设为 false 禁用；
• Preload Directives Generation：为入口 chunk 及其直接依赖自动生成 <link rel="modulepreload">；
• Async Chunk Loading Optimization：自动改写代码分割的动态 import，为公共 chunk 增加并行 preload 步骤，消除串行网络往返；
• Chunk Import Map（实验特性）：通过 build.chunkImportMap: true 启用，用 import map 将 chunk ID 映射到 URL，避免 ESM 场景下"上游 chunk 引用 URL 变化导致级联缓存失效"的问题；
• License 生成：通过 build.license: true 输出依赖许可证清单文件 .vite/license.md（可配置 fileName 自定义路径）；
• Lightning CSS：生产构建默认使用 Lightning CSS 压缩 CSS（lightningcss 是 packages/vite/package.json 的运行时依赖），PostCSS 仍用于其他 CSS 处理，css.transformer: 'lightningcss' 可整体切换到 Lightning CSS 管线。

静态资产、import.meta.glob、动态 import、Web Workers、WebAssembly 等运行时特性的完整语义（含 ?url、?raw、?worker&inline、?init 等查询参数与代码生成示例）详见 docs/guide/features.md 与 docs/guide/assets.md，端到端测试覆盖可参考 playground/assets、playground/glob-import、playground/worker、playground/wasm 等目录。

六、包导出与程序化使用（JavaScript API）

packages/vite/package.json 的 exports 字段定义了 Vite 的完整导出面，这也是插件/框架作者程序化使用 Vite 的入口：

导出	目标	用途
.	./dist/node/index.js	Node.js 主 API（createServer、build、defineConfig 等）
./module-runner	./dist/node/module-runner.js	模块运行器，用于 SSR 等场景在 Node 中执行 Vite 模块
./internal	./dist/node/internal.js	内部扩展 API（如 createBuilder 等）
./client	类型声明	客户端全局类型（import.meta.env、import.meta.hot、资产导入类型）
./dist/client/*	客户端运行时资源	注入浏览器的 client 代码
./types/*	类型文件	公共类型定义

源码子包结构（packages/vite/src）划分为 node/（服务端实现）、client/（浏览器端注入代码）、module-runner/（SSR 模块运行）、shared/（跨端共享逻辑）、types/，这一划分从源码结构看与上述 exports 面一一对应。vite/client 类型 shim 提供了资产导入类型、import.meta.env 常量类型与 import.meta.hot HMR API 类型；若需覆盖默认类型（例如把 *.svg 默认导入声明为 React 组件），需在 vite/client 引用之前添加自定义声明文件（docs/guide/features.md 的 Client Types 章节有完整示例）。

七、插件体系：Rollup 超集接口 + Rolldown 兼容性

Vite 的插件系统基于 Rollup 插件 API 的超集（详见 docs/guide/api-plugin.md），核心设计哲学（docs/guide/philosophy.md）是"精简可扩展的核心"：Vite 核心保持精简，通过强原语与 API 支撑插件生态。由于当前构建器 Rolldown 保持对 Rollup 插件接口的兼容，许多插件可以同时在 Vite 与纯 Rolldown 项目中使用。

当前 Vite 自身的构建就示范了这套工具链：

• packages/vite/rolldown.config.ts：用 Rolldown 打包 Vite 运行时；
• packages/vite/rolldown.dts.config.ts：配合 rolldown-plugin-dts 生成类型产物（build-types 脚本）；
• packages/vite/rollupLicensePlugin.ts：构建时收集依赖许可证的自定义插件实现；
• 根 package.json 的 typecheck 脚本对 packages/* 逐个执行 tsc，pnpm test 则串联 test-unit（vitest.config.ts）与 test-serve / test-build（vitest.config.e2e.ts + playground 用例）两层测试。

插件生态文档索引见 docs/plugins/index.md；官方维护的框架插件（Vue、React 等）在 vitejs 组织下，各现代框架的集成方式见 docs/guide/features.md 的 Frameworks 章节。

八、create-vite：脚手架与模板

create-vite（仓库中版本 9.2.0，bin 名 create-vite / cva，见 packages/create-vite/package.json）用于快速创建项目，交互提示基于 @clack/prompts，实现入口为 packages/create-vite/index.js。仓库中内置 17 套模板（各含 TypeScript 版本），覆盖主流框架：

• vanilla / vanilla-ts：纯 JavaScript / TypeScript（packages/create-vite/template-vanilla）
• vue / vue-ts
• react / react-ts
• preact / preact-ts
• svelte / svelte-ts
• solid / solid-ts
• lit / lit-ts
• qwik / qwik-ts

每套模板都是一个完整的可运行工程（含 index.html、vite.config.js、框架配置文件与静态资产），可直接作为学习标准项目结构的参考。创建后的默认 HMR 能力（框架级精确热更新）即由此预配置好，无需手动接线。

九、@vitejs/plugin-legacy：旧浏览器兼容构建

@vitejs/plugin-legacy（当前 8.2.3，packages/plugin-legacy）用于生成兼容旧版浏览器的 legacy 产物。从其依赖（packages/plugin-legacy/package.json）可以看到其技术路线：基于 Babel（@babel/preset-env、@babel/plugin-transform-modules-systemjs）转译为 SystemJS 模块格式，core-js 与 babel-plugin-polyfill-corejs3 提供按需 polyfill，browserslist 驱动目标浏览器检测，systemjs 作为运行时。它声明 vite: ^8.0.0 为 peer 依赖（packages/plugin-legacy/package.json）。playground 中的 playground/legacy 提供了多组配置示例（vite.config-modern-target.js、vite.config-multiple-output.js、vite.config-chunk-importmap.js 等）与对应测试（playground/legacy/tests），可用于验证 legacy 构建行为。

十、文档与进一步学习路径

仓库内文档站点位于 docs（Astro 站点，pnpm docs 本地启动），推荐阅读路径：

• docs/guide/index.md：快速上手（index.html 与项目根、安装、基本用法）；
• docs/guide/features.md：特性大全（本文第三、五节内容的完整展开）；
• docs/guide/dep-pre-bundling.md：依赖预打包原理与缓存配置；
• docs/config：全部配置项（shared-options.md、server-options.md、ssr-options.md、worker-options.md 等）；
• docs/guide/api-plugin.md / docs/guide/api-javascript.md / docs/guide/api-hmr.md：插件 API、JS API 与 HMR API 参考；
• docs/guide/ssr.md：SSR 指南（配合 ./module-runner 导出）；
• docs/guide/migration.md 与 docs/changes：版本迁移与重大变更说明。

十一、小结：从源码看 Vite 的工程取舍

综合 README 与源码实现，可以归纳出当前 Vite 的工程取向：

1. 双形态架构：Dev 走"原生 ESM + 按需编译 + Rolldown 预打包"，Build 走 Rolldown 全量打包（createBuilder），两者共享同一插件超集接口；
2. 性能优先的工具链选择：运行时依赖中保留 esbuild 作为可选 peer（用于压缩/转换场景），而核心转译与预打包已切换到 Oxc 与 Rolldown 工具链（features 文档与 docs/guide/philosophy.md 均强调基于 Oxc 工具链与 Rolldown 实现密集任务）；
3. 强类型交付：client.d.ts、types/、exports 中显式的 ./types/* 通道，以及 pnpm typecheck 对多 tsconfig 项目（src/node、src/client、src/module-runner 等）的逐一校验（packages/vite/package.json），共同支撑 "Fully Typed APIs" 这一承诺；
4. 测试驱动的稳定性：playground 下近百个端到端用例目录（serve/build 双模式测试，VITE_TEST_BUILD=1 切换），是理解每个特性"实际行为边界"的最直接材料。

对使用者而言：用 create-vite 选模板起步，vite dev 开发、vite build 产出、vite preview 验收，旧浏览器兼容交给 @vitejs/plugin-legacy，深度定制则通过 Rollup 超集插件 API 与类型化 JS API 完成——这就是当前 Vite 提供的完整工具链面貌。