"Error: In this configuration Angular requires Zone.js" when testing Angular library (v21) with Vitest

近日，不少使用Angular v21的开发者在进行库（library）的单元测试时，遇到了一个令人困惑的错误信息：“Error: In this configuration Angular requires Zone.js”。该问题出现在采用Vitest作为测试运行器的场景中，导致测试无法正常启动。本文将详细解析这一错误的成因，并提供切实可行的解决方案。

错误现象与背景

当开发者创建一个Angular库（例如通过ng g library生成），并配置Vitest进行测试时，运行测试命令后控制台往往会输出类似如下的错误堆栈：

Error: In this configuration Angular requires Zone.js
    at new NgZoneImpl (webpack:...)
    at ...

此错误明确指出，当前Angular配置要求必须存在Zone.js，但运行时未能找到或正确加载。为什么在传统的Karma测试中从未遇到此问题？这是因为Angular的变更检测机制高度依赖Zone.js——一个拦截异步操作并通知Angular进行变化检测的库。在Jasmine/Karma测试环境中，Zone.js通常由Angular CLI自动注入；但切换到Vitest后，由于测试执行环境（Node.js或JSDOM）与浏览器差异，Zone.js默认不活跃，从而触发错误。

原因深入分析

Vitest基于Vite，默认运行在Node.js环境中，通过jsdom模拟浏览器行为。而Angular的@angular/core包在初始化NgZone时，会检查全局Zone对象是否存在。若不存在，则抛出上述错误。Angular v21依然保留了对Zone.js的硬性依赖，尽管Angular 18+已开始探索“无Zone”的增量DOM，但对于大多数组件及模板绑定，Zone.js仍是必需项。

此外，当测试Angular库（而非应用）时，通常不会默认加载zone-testing（用于模拟异步测试的Zone补丁），导致Zone对象仅包含基础API，而缺少与JSDOM的集成补丁，进而引发初始化失败。

解决方案：三步配置Vitest

1. 安装必要的依赖

确保项目中已安装zone.js和@types/jasmine（或vitest本身）。在库的package.json中应显式声明：

npm install zone.js --save-dev

如果使用JSDOM模拟浏览器环境，还需安装jsdom：

npm install jsdom --save-dev

2. 创建Vitest配置文件

在项目根目录或库目录下创建vitest.config.ts（或vitest.config.js），并进行如下配置：

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environment: 'jsdom',
    setupFiles: ['./src/setup-tests.ts'],
  },
});

关键点在于setupFiles：我们需要一个初始化文件来导入Zone.js及其测试补丁。

3. 编写setup文件

新建src/setup-tests.ts（路径可根据项目调整），内容如下：

import 'zone.js';
import 'zone.js/testing';

这两行导入完成两件事：第一行将Zone.js核心API注入全局；第二行加载zone-testing模块，该模块会添加fakeAsync、async等测试辅助函数，并正确初始化Angular的Zone。注意：顺序很重要，必须先导入核心库，再导入测试补丁。

如果仍然报错，可能还需在vitest.config.ts中添加globals: true配置，以确保Zone作为全局变量：

export default defineConfig({
  test: {
    globals: true, // 允许直接使用Zone等全局变量
    environment: 'jsdom',
    setupFiles: ['./src/setup-tests.ts'],
  },
});

进阶建议：优化测试体验

对于Angular库开发者，以下实践可进一步提升测试效率：

使用@analogjs/vite-plugin-angular：AnalogJS社区提供的Vite插件可简化Angular与Vite的集成，自动处理Zone.js和组件编译。在vite.config.ts中添加该插件后，Vitest配置可大幅简化。
避免过早迁移所有测试：若项目已成熟，建议逐步迁移。先为核心服务（Service）编写Vitest测试（这些通常不依赖Zone），再处理组件（Component）。组件测试必须确保Zone.js正确加载。
考虑Angular 18+的“无Zone”模式：Angular团队正推广provideExperimentalZonelessChangeDetection()，但需注意该API尚为实验性，且对测试环境有额外要求（需配置特定Zone补丁），目前仍推荐保持Zone.js兼容。

结语

“Error: In this configuration Angular requires Zone.js”本质上是一个环境配置问题，而非Angular或Vitest的缺陷。通过正确导入Zone.js及其测试补丁，并在Vitest的setup文件中初始化，库开发者可以无缝地利用Vitest的高速执行和Vite的即时反馈。随着Angular生态逐步拥抱Vite，此类配置问题将愈发常见，掌握解决方案是提升开发效率的关键。希望本文能助你快速排除故障，专注于更有价值的测试逻辑编写。

&quot;Error: In this configuration Angular requires Zone.js&quot; when testing Angular library (v21) with Vitest