1. 项目背景

Vitest 由 Anthony Fu 和 VoidZero 团队于 2021 年创建,目标是解决前端测试领域的一个长期痛点:测试框架与构建工具的割裂。Jest 虽然生态成熟,但其基于 jest-runtime 的模块系统需要额外配置才能理解 TypeScript、ESM、JSX 等现代语法——而这些恰好是 Vite 天然支持的。

Vitest 的核心洞察:复用 Vite 的转换管道(transform pipeline)、解析器(resolver)和插件系统,零配置即可获得与开发环境一致的测试运行环境。这不仅消除了配置负担,更重要的是确保了测试行为与应用运行行为完全一致。

🪄 设计哲学

一个配置,两处运行。 你的 vite.config.ts 既用于开发/构建,也直接驱动测试——不需要 jest.config.js、babel.config.js 等叠加配置。

解决的问题:

  • Jest 配置繁琐(TypeScript/ESM/CSS Modules 需要额外 transformer)
  • Jest 启动慢(vitest 的 watch 模式利用 Vite 的 HMR 机制实现毫秒级重跑)
  • 测试环境与开发环境不一致(不同的模块解析、不同的转换规则)
  • 缺乏原生 ESM 支持(vitest 原生支持 top-level await、import.meta)

2. 快速上手

最小可运行示例——3 行代码开始测试:

sum.test.ts 零配置,直接运行
import { expect, test } from 'vitest'
import { sum } from './sum'

test('adds 1 + 2 to equal 3', () => {
  expect(sum(1, 2)).toBe(3)
})

常见场景:

带 Mock 的测试
import { vi, test, expect } from 'vitest'
import { fetchUser } from './api'

// Mock 一个模块
vi.mock('./api', () => ({
  fetchUser: vi.fn(() => Promise.resolve({ name: 'Alice' }))
}))

test('mock example', async () => {
  const user = await fetchUser(1)
  expect(user.name).toBe('Alice')
  expect(fetchUser).toHaveBeenCalledWith(1)
})
快照测试
import { expect, test } from 'vitest'

test('snapshot', () => {
  const data = { id: 1, items: ['a', 'b', 'c'] }
  expect(data).toMatchSnapshot()
})

3. 工程化方案

类别工具配置
包管理pnpm (v11)pnpm-workspace.yaml — catalog 模式统一版本
构建Rollup + tsup每个子包独立 rollup.config.js
TypeScripttsc + unplugin-isolated-decl项目级 tsconfig.json + 子包 tsconfig.json
LintESLint (flat config)@antfu/eslint-config + 根目录 eslint.config.js
测试Vitest 自身自举测试——Vitest 用 Vitest 测试自己
CI/CDGitHub Actions多 Node 版本矩阵 + 浏览器测试 (Playwright)

值得学习的工程化实践:

  • Catalog 模式:pnpm-workspace.yaml 中用 catalog 字段统一管理所有依赖版本,避免版本漂移
  • Patch 管理:对上游依赖的修改通过 patches/ 目录 + pnpm 的 patchedDependencies 机制管理
  • 自举测试:test/ 目录下的集成测试使用 vitest 本身运行,保证发布质量
  • 多构建产物:每个子包独立构建,通过 exports 字段细粒度控制导出

4. 项目制品

包名npm职责
vitest主包CLI、配置、Node API、Browser API
@vitest/runner内部测试执行引擎(suite/test/钩子)
@vitest/mocker内部模块模拟系统(vi.mock / vi.spyOn)
@vitest/expect内部断言库(Jest + Chai 兼容)
@vitest/spy内部Spy / Stub 实现
@vitest/snapshot内部快照管理
@vitest/utils内部工具函数、diff 算法、序列化
@vitest/ui可选Web UI 界面
@vitest/browser可选浏览器模式核心
@vitest/coverage-v8可选V8 原生覆盖率
@vitest/coverage-istanbul可选Istanbul 覆盖率
@vitest/browser-playwright可选Playwright 浏览器集成
@vitest/browser-webdriverio可选WebdriverIO 浏览器集成
@vitest/pretty-format内部格式化输出(类 jest 的 pretty-format)
@vitest/web-worker内部Web Worker 支持

5. 项目结构

# Vitest Monorepo — 16 个子包 vitest/ ├── packages/ 核心源码(16 子包) │ ├── vitest/ ★ 主包:CLI / 配置 / Node API / Browser API │ │ └── src/ │ │ ├── node/ CLI入口、配置解析、ViteDevServer管理、项目池 │ │ ├── runtime/ worker 内执行逻辑、测试运行、环境配置 │ │ ├── integrations/spy/coverage/globals/vi 对象桥接 │ │ ├── types/ 全局类型定义 │ │ ├── utils/ 工具函数 │ │ └── public/ 公共导出入口 │ ├── runner/ ★ 测试执行引擎:suite/test/hooks/并发控制 │ ├── mocker/ ★ 模块模拟:vi.mock/vi.spyOn/自动mock │ │ ├── src/node/ Node 端:Vite 插件拦截模块加载 │ │ └── src/browser/ 浏览器端:MSW/Native 拦截 │ ├── expect/ 断言库:Jest expect + Chai 双API兼容 │ ├── snapshot/ 快照系统:存储、比对、更新、内联快照 │ ├── spy/ Spy 实现:函数调用追踪 │ ├── utils/ 通用工具:diff算法、序列化、Nanoid │ ├── ui/ Web UI:可视化测试报告 │ ├── browser/ 浏览器模式核心:WebSocket通信、iframe管理 │ └── ... ├── test/ 集成测试(大量端到端用例) ├── docs/ 文档站点(VitePress) └── examples/ 示例项目

6. 核心链路概览

6.1 一次完整测试运行的生命周期

  1. CLI 启动
    packages/vitest/src/node/cli.ts → 使用 cac 解析命令行参数 → 创建 Vitest 实例
  2. 配置解析
    packages/vitest/src/node/core.ts:252 → resolveConfig() 合并 CLI 选项 + vite.config.ts + vitest 默认值
  3. Vite Server 创建
    复用或创建 ViteDevServer → 注册 vitest 插件 → 配置模块解析
  4. 项目发现
    resolveProjects() → 扫描 workspace 中的 test projects → 创建 TestProject 实例
  5. 文件收集
    VitestSpecifications → 根据 include/exclude 模式找到测试文件 → AST 分析提取测试元数据
  6. Worker 池分配
    ProcessPool → 根据 pool 配置(threads/forks/vmThreads)创建 worker 进程
  7. 模块加载与转换
    Worker 内通过 Vite 的 SSR 模块图 加载测试文件 → Vite 插件管道转换 TS/JSX/CSS
  8. 测试执行
    @vitest/runner → startTests() → 按序执行 suite → beforeEach → test → afterEach
  9. 结果报告
    Reporter 管道 → 终端输出 / JSON / JUnit / HTML 报告

6.2 核心数据流

graph LR
    A[CLI 参数] --> B[Vitest 实例]
    B --> C[ViteDevServer]
    B --> D[resolveConfig]
    D --> E[TestProject x N]
    E --> F[Worker Pool]
    F --> G[Worker 进程]
    G --> H[模块加载 via Vite SSR]
    H --> I[@vitest/runner]
    I --> J[Test Results]
    J --> K[Reporter]
    K --> L[终端/JSON/JUnit/HTML]
    M[Mocker Plugin] -.-> H
    N[Coverage Provider] -.-> I

图:Vitest 核心数据流 —— 从 CLI 到测试报告的完整链路

6.3 推荐阅读路径

  1. 1packages/vitest/src/node/cli.tsCLI 入口,创建 Vitest 实例
  2. 2packages/vitest/src/node/core.tsVitest 核心类:生命周期管理、配置、项目池
  3. 3packages/vitest/src/node/pool.tsWorker 线程/进程池管理
  4. 4packages/vitest/src/runtime/runBaseTests.tsWorker 内测试执行入口
  5. 5packages/runner/src/run.tsRunner 核心:startTests / 钩子 / 并发控制
  6. 6packages/runner/src/suite.tssuite/test API 定义与 task 构建
  7. 7packages/mocker/src/node/Mocker:Vite 插件拦截 + 自动 mock

6.4 关键代码速览

packages/vitest/src/node/core.ts:69-185 IDE 打开
// ★ Vitest 核心类:整个测试运行器的中枢
export class Vitest {
  public readonly version = version
  public readonly logger: Logger
  public readonly packageInstaller: VitestPackageInstaller
  public readonly watcher: VitestWatcher
  public projects: TestProject[] = []
  public vcs: VCSProvider

  // ★ 构造时仅做最基础的初始化
  constructor(modeOrCliOptions, cliOptionsOrOptions?, maybeOptions?) {
    this._cliOptions = cliOptions
    this.logger = new Logger(this, options.stdout, options.stderr)
    this.packageInstaller = options.packageInstaller || new VitestPackageInstaller()
    this.specifications = new VitestSpecifications(this)
    this.watcher = new VitestWatcher(this)
  }
}
packages/runner/src/run.ts:36-38 IDE 打开
// ★ Runner 使用高性能计时器
const now = globalThis.performance
  ? globalThis.performance.now.bind(globalThis.performance)
  : Date.now
const unixNow = Date.now
const { clearTimeout, setTimeout } = getSafeTimers()

7. 架构总图

graph TB
    subgraph "Main Process (Node.js)"
        CLI["cac CLI
cli.ts"] V["Vitest 实例
core.ts (1707行)"] CFG["resolveConfig
合并 vite 配置"] VS["ViteDevServer
复用 Vite 插件体系"] TP["TestProject × N
project.ts"] SPEC["VitestSpecifications
文件发现 + AST"] POOL["ProcessPool
Worker 管理"] REP["Reporter 管道
终端/JUnit/JSON/Blob"] end subgraph "Worker Process" WE["Worker 入口
runBaseTests.ts"] VL["Vite SSR 模块加载
转换 TS/JSX/CSS"] RUN["@vitest/runner
run.ts / suite.ts"] MK["@vitest/mocker
vi.mock 拦截"] EXP["@vitest/expect
断言匹配"] SN["@vitest/snapshot
快照比对"] end subgraph "Browser" BM["Browser Mode
Playwright / WebDriverIO"] end CLI --> V V --> CFG CFG --> VS VS --> TP TP --> SPEC SPEC --> POOL POOL --> WE WE --> VL VL --> RUN MK -.-> VL RUN --> EXP RUN --> SN RUN --> REP BM -.-> WE style V fill:#7c3aed,color:#fff style RUN fill:#2563eb,color:#fff style MK fill:#059669,color:#fff

图:Vitest 架构总图 —— 主进程、Worker 进程、浏览器模式三层协作

8. 模块深度导航

9. 同类库对比

维度VitestJestMocha
配置复杂度零配置(复用 Vite)需 babel/ts-jest需手动组装
ESM 支持原生 ESM first实验性支持需额外配置
Watch 模式HMR 级别(毫秒)基于文件变更需插件
覆盖率V8 原生 + IstanbulIstanbul需 nyc/c8
浏览器测试✅ 原生支持❌ jsdom 模拟❌ 需 Karma
TypeScript开箱即用需额外配置需 ts-node
MonorepoWorkspace 原生projects 配置需手动组织
兼容性Jest API 兼容—风格差异大
🧠 设计取舍

为什么基于 Vite 而不是自己实现模块加载?

复用 Vite 的转换管道意味着 Vitest 天然支持 Vite 生态中的所有插件和配置。这不是一个"偷懒"的决定,而是一个架构级的判断:测试框架不需要也不应该重新发明模块加载。这不仅减少了维护负担,更重要的是保证了测试环境与打包环境的行为一致性。

10. 学习要点总结

🏗️ 架构能力学习价值
Vite 插件体系复用理解"组合优于继承"在构建工具中的实践
Monorepo 架构16 个包的职责划分、依赖管理、Catalog 模式
Worker 进程池多线程测试执行的隔离与通信 (birpc)
插件化 MockerVite 插件拦截 + 运行时反射的动态 mock 机制
双 API 兼容Jest expect + Chai 双接口的设计模式
浏览器模式iframe 沙箱 + CDP 协议 + WebSocket 通信

💡 一句话总结

Vitest 不是"更好的 Jest"——它是利用 Vite 生态系统重新思考测试框架的产物。它的最大创新不是某个具体功能,而是证明了 构建工具和测试框架可以共享同一条管道,从而消除了前端开发中"配置地狱"的最后一公里。