Happy DOM：Vitest 默认推荐的无头 DOM 环境，凭什么从 jsdom 嘴里抢市场
阅读时间: 大约 7 分钟
Happy DOM：Vitest 默认推荐的无头 DOM 环境，凭什么从 jsdom 嘴里抢市场
前端单元测试有个基础设施级的问题：在 Node.js 里跑测试时，根本没有浏览器，document、window、HTMLElement 这些对象从哪来？过去十几年答案几乎只有一个——jsdom。它是用 JavaScript 写的 DOM 实现，能在 Node 里模拟出一个”够用”的浏览器环境。但 jsdom 维护节奏慢、在大型测试套件里偏重，成了 Vite/Bun 这波”追求极速”浪潮下的瓶颈。Happy DOM 就是来替代它的：一个 TypeScript 重写的无头浏览器实现，2019 年由 David Ortner 创建（MIT 协议），如今被 Vitest 列为推荐测试环境。本文基于官方 GitHub 仓库实读分析。
一、它是什么：一个没有 GUI 的浏览器
官方 README 的自我定位很简短（整个 README 只有 62 行、1.89KB，见上图）：“A JavaScript implementation of a web browser without its graphical user interface”——一个没有图形界面的浏览器实现。它提供完整的 DOM API 供测试与 SSR 使用，官方列出的能力包括：
- Custom Elements（Web Components）；
- 声明式 Shadow DOM；
- Mutation Observer；
- Tree Walker；
- Fetch API。
官方宣称的适配面：Vitest、Bun、Jest、Testing Library，以及 React、Vue、Svelte、Angular、LitElement 等主流框架——也就是说，主流组件库的测试都能在它上面跑。
二、规模与活跃度：6 万仓库在用
GitHub 仓库侧栏数据（本文写作时实读）：
- 被 60,394 个仓库标记为依赖；
- 发布了 715 个 release，最新版 v20.14.5；
- 171 个外部贡献者；
- 99.1% 代码是 TypeScript；
- 但同时挂着 341 个 open issue、123 个 open PR——对于一个基础设施工具，这个积压量值得关注。
版本号已经到 v20，说明迭代非常频繁（715 个 release 摊到 7 年，平均一年上百个版本）。这种高频迭代既是活跃的证明，也意味着 API 表面在快速变动。
三、速度优势：官方不吹，社区在测
有意思的是，Happy DOM 官方 README 里没有附任何性能 benchmark——它不像 Oxfmt 那样把对比图贴在脸上。速度叙事主要来自社区实测（注意：以下为第三方数据，非官方口径）：
- pkgpulse 2026 年 3 月的 Vitest 实测（100 个组件测试）：happy-dom 4.2s，jsdom 31.5s（约 7.5 倍差距），Playwright 真浏览器 8.1s；
- 日本 T-CREATOR 的 Jest 对比：happy-dom 8.7s vs jsdom 42.3s，约 4.9 倍；
- 西班牙 Dominicode 2026 年 7 月的四组对比：happy-dom 快 1.45–1.83 倍。
可以看到，“快多少”高度取决于测试套件形态：简单渲染-查询场景差距最大（数倍），复杂交互场景差距收窄到 1.5 倍左右。这与 jsdom 的慢主要慢在初始化和不常用 API 的观点吻合。
四、口径与局限（重点）
- API 覆盖度不如 jsdom。 这是官方和社区共识：Happy DOM 是”够用优先”的重写，遇到冷门 DOM 特性、边缘 CSSOM、罕见事件顺序时，可能报”not implemented”。Koala 点评也直接指出”遇到冷门 DOM 特性偶尔需要绕路”。Vitest 默认推 happy-dom 是”大多数项目更快够用”的折中，不是”全面替代”。
- 341 个 open issue 是信号。 基础库 issue 积压多，说明兼容问题层出不穷——迁移后遇到怪异 bug 的概率不低，要把”排查 happy-dom 兼容性”纳入项目风险。
- 不是真浏览器。 它不做布局、不跑样式引擎、没有真实渲染管线——需要验证真实浏览器行为的测试（视觉、布局、真实事件），它替代不了 Playwright/Cypress。社区实测里 Playwright 真浏览器 8.1s 反而是这个定位的参照。
- “Vitest 默认推荐”要准确理解。 Vitest 把 happy-dom 作为可选环境之一列出，并非所有项目开箱即用；从 jsdom 迁移时仍需逐个跑通测试套件。
五、客观评价
优势：
- 对主流框架测试套件，普遍比 jsdom 快 2–5 倍，大套件 CI 时间节省可观；
- TypeScript 原生，类型定义现代；
- Web Components / Shadow DOM / Fetch 这些现代 API 支持跟上了；
- 生态位正：Vitest/Bun 都在推。
局限：
- API 覆盖边界清晰但窄，冷门特性要自己补 stub；
- issue 积压不少，修 bug 等上游的节奏不可控；
- 高频发版对锁定版本的项目是维护负担；
- 仍然是模拟环境，不能替代真实浏览器端到端测试。
六、谁该用
用 Vitest/Bun 跑组件测试、被 jsdom 拖慢 CI 的团队——值得切过去试跑，大概率变快。依赖罕见 DOM API、或对测试保真度要求苛刻（要逼近真实浏览器）的项目，留在 jsdom 或直接上真浏览器。新项目起步，直接选 happy-dom 作为默认环境是合理的现代默认。