Angular 21 中如何配置 Vitest 调试与无头测试？

2026-11-06数据阿明

结论

可以在 Angular CLI 的 runnerConfig 中指定 Vitest 配置文件，再通过 ng test --configuration=debug 切换到本地调试配置。下面以 Playwright 浏览器 provider 为例：调试配置会启动带有 --remote-debugging-port=9333 参数的有头 Chromium，CI 配置则启动无头 Chromium。

原问题里的 customLauncher、--browsers ChromeDebug 和 --karma-config karma.conf.js 用于 Karma 工作流。迁移到 Vitest 后，需改用 Angular 的 @angular/build:unit-test builder 和 Vitest browser provider。Angular 当前文档允许在 angular.json 的 test target 中设置 runnerConfig；Playwright provider 会将 launchOptions 传给浏览器启动命令。Angular 测试配置；Vitest Playwright 配置

配置步骤

先安装 Playwright browser provider：

npm install --save-dev @vitest/browser-playwright

在 angular.json 中为默认运行和调试命令分别指定配置文件。将 your-project-name 替换为实际项目名。如果 test target 已有其他选项，请保留并合并到下面的配置中：

{
  "projects": {
    "your-project-name": {
      "architect": {
        "test": {
          "builder": "@angular/build:unit-test",
          "options": {
            "runnerConfig": "vitest.ci.config.ts",
            "watch": false
          },
          "configurations": {
            "debug": {
              "runnerConfig": "vitest.debug.config.ts",
              "watch": true
            },
            "ci": {
              "runnerConfig": "vitest.ci.config.ts",
              "watch": false
            }
          }
        }
      }
    }
  }
}

创建 vitest.debug.config.ts：

import { defineConfig } from 'vitest/config'
import { playwright } from '@vitest/browser-playwright'

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      headless: false,
      provider: playwright({
        launchOptions: {
          args: ['--remote-debugging-port=9333'],
        },
      }),
      instances: [{ browser: 'chromium' }],
    },
  },
})

创建 vitest.ci.config.ts：

import { defineConfig } from 'vitest/config'
import { playwright } from '@vitest/browser-playwright'

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      headless: true,
      provider: playwright(),
      instances: [{ browser: 'chromium' }],
    },
  },
})

然后运行相应命令：

# 使用默认配置：无头浏览器，适合 CI
ng test

# 明确选择 CI 配置
ng test --configuration=ci

# 在本地启动有头 Chromium，供 VS Code 连接调试
ng test --configuration=debug

VS Code 的 Chrome 调试配置可以连接本地 9333 端口。启动参数中的端口应与调试配置一致，启动前还要确认没有其他 Chrome 进程占用该端口。

注意事项

示例假设项目使用 @angular/build:unit-test，并已安装与项目兼容的 Vitest 和 Playwright provider。如果 test target 使用其他 builder，请根据项目配置调整。
Angular CLI 会将 runnerConfig 指向的文件用于高级 Vitest 设置，并可能覆盖 test.projects、test.include 等字段。不要依赖这些字段通过自定义配置改变 Angular 的测试发现行为。Angular Vitest 迁移说明
示例使用浏览器模式。如果单元测试只需在 Node.js 环境运行，Angular 默认的 Vitest 配置通常无需启动浏览器。此时可让默认 target 使用项目的 Node 测试配置，只在 debug 配置中启用 browser provider。
调试端口参数会传给 Playwright 启动 Chromium。如果所用的浏览器 provider 或浏览器版本不接受该参数，请按对应 provider 的启动选项调整。