Read OSS
vitejs/vite

入口点与启动流程

•中级

前置知识

  • ›对 ES modules 有基本了解
  • ›熟悉 Node.js CLI 基础知识
  • ›了解 package.json 的 bin 字段

入口点与启动流程

Vite 的入口点出奇地简洁。整个代码库超过 5 万行，但从终端输入 vite 到开发服务器正常运行，中间只经过寥寥几个文件。这并非偶然——Vite 的架构有着清晰的关注点分离，每一层只做好一件事。

接下来，让我们沿着启动链路，从 CLI 命令一路追踪到开发服务器的运行，理解其中每个设计决策背后的原因。

bin 入口

当你运行 vite 或 vite dev 时，shell 会通过 packages/vite/package.json 中的 bin 字段解析命令，最终指向 packages/vite/bin/vite.js——一个刻意保持精简的文件。

这个 bin 文件本身几乎什么都不做：记录启动时间、从 process.argv 中解析 debug 和 filter 标志、启用 Node.js 编译缓存，然后动态 import CLI 模块。"bin 入口保持轻量、核心逻辑放在模块中"是 Node.js 生态系统中常见的模式，它能让启动更快，也让真正的业务逻辑更易于测试。

flowchart TD
    A["$ vite dev"] --> B["bin/vite.js"]
    B --> C["cli.ts — parse args with cac"]
    C --> D{Command?}
    D -->|dev| E["createServer()"]
    D -->|build| F["build()"]
    D -->|preview| G["preview()"]
    D -->|optimize| H["optimizeDeps()"]
    E --> I["resolveConfig()"]
    I --> J["Plugin container init"]
    J --> K["HTTP server + HMR"]

CLI 参数解析

真正的 CLI 逻辑位于 packages/vite/src/node/cli.ts。Vite 使用 cac 作为参数解析库——它是 commander、yargs 等库的轻量级替代方案。如果你没用过 cac，不用担心，它的 API 和 commander 几乎一样。关键在于，每个子命令（dev、build、preview）都对应各自独立的处理函数。

有一个细节值得注意：dev 命令同时也是默认命令。直接运行 vite 而不带任何子命令，效果等同于 vite dev。这是通过 cac 的默认命令功能实现的。

提示：建议从头到尾通读一遍 cli.ts。这个文件结构清晰，每个 flag 都对应一个配置选项。当你对某个 CLI 标志的作用感到困惑时，这里就是最权威的参考。

配置解析

在任何实质性工作开始之前，Vite 需要先完成配置解析。config.ts 中的 resolveConfig 函数是整个代码库中最重要的函数之一。

配置解析遵循分层合并的方式：

  1. 内联配置——通过 API 直接传入的选项（例如 createServer({ root: './app' })）
  2. 配置文件——vite.config.ts、vite.config.js 或其他支持的格式
  3. 默认值——所有选项的合理兜底值
flowchart LR
    A["Inline config"] --> D["mergeConfig()"]
    B["vite.config.ts"] --> D
    C["Defaults"] --> D
    D --> E["ResolvedConfig"]
    E --> F["Plugins sorted & applied"]

配置文件的加载过程出乎意料地复杂。Vite 需要处理 TypeScript 配置文件、ESM 与 CJS 格式的差异，甚至还要支持从 node_modules 中导入内容的配置文件。默认情况下，Vite 会在启动时用 Rolldown 对配置文件进行打包处理——没错，Vite 用自己的 bundler 来构建自己的配置文件。这个设计乍看让人意外，但回过头来想，它其实是解决这一问题最自然的方案。

服务器创建：开发模式的核心

createServer 函数负责编排开发服务器所需的一切。仔细阅读这个函数很有价值，因为它直接体现了 Vite 的架构哲学：通过一个共享上下文对象将各个独立子系统组合在一起。

createServer 按顺序完成以下初始化：

  1. 配置解析——将用户配置与默认值合并，如上所述
  2. Plugin container——初始化兼容 Rollup 的插件管道
  3. Module graph——创建 ModuleGraph 实例，用于追踪所有模块及其依赖关系
  4. WebSocket 服务器——处理与浏览器之间的 HMR 通信
  5. 文件监听器——通过 chokidar 监听项目文件变化
  6. Connect middleware 栈——用于提供经过转换的模块的 HTTP 服务器

服务器对象本身充当共享上下文。每个子系统都持有对它的引用，并通过这个共享引用相互调用。这是对事件驱动架构的一种有意替代——更加显式，也更易于调试。

提示：要了解服务器能做什么，最好的方式是查看 server/index.ts 中的 ViteDevServer 接口。建议先通读类型定义，再深入实现细节。

Module Graph

packages/vite/src/node/server/moduleGraph.ts 中的 EnvironmentModuleGraph 类值得重点关注。它是支撑 Vite HMR 高效运行的核心数据结构——当文件发生变化时，module graph 能精确知道哪些模块受到了影响、需要让浏览器重新获取。（mixedModuleGraph.ts 中有一个向后兼容的 ModuleGraph 包装器，用于聚合各环境的图。）

图中的每个节点（EnvironmentModuleNode）记录了以下信息：

  • 模块的 URL 和文件路径
  • 该模块导入了哪些模块（importedModules）
  • 哪些模块导入了它（importers）
  • 是否已接受 HMR 更新
  • 最后一次 transform 的时间戳
graph TD
    A["main.ts"] --> B["App.vue"]
    A --> C["router.ts"]
    B --> D["Header.vue"]
    B --> E["Footer.vue"]
    C --> F["routes/Home.vue"]
    C --> G["routes/About.vue"]
    style A fill:#e8f4fd,stroke:#333
    style B fill:#fde8e8,stroke:#333

当 Header.vue 发生变化时，module graph 会沿着 importer 链向上查找最近的 HMR 边界。如果 App.vue 声明了接受子模块的 HMR 更新，那么只有这个子树会被标记为失效。这正是 Vite 实现近乎即时 HMR 的关键——它从不做超出必要范围的失效处理。

阅读源码前需要了解的知识

要高效地阅读 Vite 的源码，建议提前熟悉以下概念：

  • Rollup plugin API——Vite 在 Rollup 插件接口的基础上扩展了额外的开发时 hook。理解 Rollup 插件，就掌握了 Vite 插件系统 80% 的内容。
  • ES module 语义——import.meta、动态 import()，以及浏览器处理原生 ESM 的方式。这是 Vite 架构得以成立的根本基础。
  • Node.js HTTP 服务器——Vite 使用 connect 作为 middleware 框架。它比 Express 简单得多，这种简单性是有意为之的。
  • Rolldown 与 OXC——Rolldown 用于依赖预打包和生产构建，OXC 负责 TypeScript/JSX 的转译。了解这两个工具，有助于理解 Vite 8 的性能特性。

目录索引

以下是本文涉及关键文件的快速参考：

路径 用途
packages/vite/bin/vite.js 精简的 bin 入口点
packages/vite/src/node/cli.ts 使用 cac 进行 CLI 参数解析
packages/vite/src/node/config.ts 配置解析与合并
packages/vite/src/node/server/index.ts 开发服务器的创建与编排
packages/vite/src/node/server/moduleGraph.ts 各环境的模块依赖图
packages/vite/src/node/plugins/ 内置 plugin 的实现

下一步

下一篇文章将深入探讨插件系统——Vite 如何扩展 Rollup 的插件接口、插件的执行顺序，以及 plugin container 如何在开发阶段对模块进行实时转换。