配置 Vitest

要创建 Vitest 配置文件，请遵循本指南。在继续之前，请确保你了解 Vitest 配置解析的机制。

WARNING

此处列出的所有选项都位于配置中的 test 属性内：

export default defineConfig({
  test: {
    exclude: [],
  },
});

TIP

除了以下选项外，你还可以使用 Vite 中的任何配置选项。例如，使用 define 定义全局变量，或使用 resolve.alias 定义别名。

所有在 工作区 项目配置中不支持的配置选项旁边都有 * 标识。

include

• 类型： string[]
• 默认值： ['**/*.{test,spec}.?(c|m)[jt]s?(x)']
• CLI： vitest [...include], vitest **/*.test.js

匹配测试文件的 glob 模式列表。

注意

使用 coverage 时，Vitest 会自动将测试文件的 include 模式添加到 coverage 的默认 exclude 模式中。参见 coverage.exclude。

exclude

• 类型： string[]
• 默认值： ['**/node_modules/**', '**/dist/**', '**/cypress/**', '**/.{idea,git,cache,output,temp}/**', '**/{karma,rollup,webpack,vite,vitest,jest,ava,babel,nyc,cypress,tsup,build}.config.*']
• CLI： vitest --exclude "**/excluded-file"

需要从测试文件中排除的 glob 模式列表。

WARNING

此选项不影响覆盖率。如果需要从覆盖率报告中排除某些文件，请使用 coverage.exclude。

这是唯一一个通过 CLI 标志提供时，不会覆盖配置的选项。通过 --exclude 标志添加的所有 glob 模式都将追加到配置的 exclude 列表中。

includeSource

• 类型： string[]
• 默认值： []

用于源内测试文件的 include glob 模式。

定义后，Vitest 将运行所有匹配的文件，这些文件内部包含 import.meta.vitest。

server

• 类型： { sourcemap?, deps?, ... }

Vite-Node 服务器选项。

server.sourcemap

• 类型： 'inline' | boolean
• 默认值： 'inline'

将内联源映射注入到模块中。

server.debug

• 类型： { dumpModules?, loadDumppedModules? }

Vite-Node 调试器选项。

server.debug.dumpModules

• 类型： boolean | string

将转换后的模块导出到文件系统。传递字符串将导出到指定路径。

server.debug.loadDumppedModules

• 类型： boolean

如果存在，则从文件系统读取转储的模块。通过修改文件系统中的转储结果，可以用于调试。

server.deps

• 类型： { external?, inline?, ... }

处理依赖解析。

server.deps.external

• 类型： (string | RegExp)[]
• 默认值： [/\/node_modules\//]

外部化意味着 Vite 将跳过对该包的处理，直接使用原生 Node。外部化的依赖项将不应用于 Vite 的转换器和解析器，因此它们不支持重新加载时的 HMR。默认情况下，node_modules 中的所有包都已外部化。

这些选项支持包名称（格式与 node_modules 中的写法一致），或在 deps.moduleDirectories 中指定的路径。例如，位于 packages/some-name 中的包 @company/some-name 应指定为 some-name，并且 packages 应包含在 deps.moduleDirectories 中。基本上，Vitest 始终检查文件路径，而不是实际的包名称。

如果使用 RegExp，Vitest 会在文件路径上调用它，而不是包名称。

server.deps.inline

• 类型： (string | RegExp)[] | true
• 默认值： []

Vite 将处理内联模块。这有助于处理以 ESM 格式发布的 .js 包（Node 无法处理）。

如果设置为 true，则每个依赖项都将内联。默认情况下，将内联 ssr.noExternal 中指定的所有依赖项。

server.deps.fallbackCJS

• 类型： boolean
• 默认值： false

当依赖项是有效的 ESM 包时，尝试根据路径推测 CJS 版本。如果依赖项具有错误的 ESM 文件，这可能会有所帮助。

如果同一个包在 ESM 和 CJS 模式下有不同的实现逻辑，这可能会导致行为不一致。

server.deps.cacheDir

• 类型： string
• 默认值： 'node_modules/.vite'

用于存储缓存文件的目录。

deps

• 类型： { optimizer?, ... }

处理依赖解析。

deps.optimizer

• 类型： { ssr?, web? }
• 另请参阅： 依赖项优化选项

启用依赖优化。如果你有很多测试，这可能会提高它们的性能。

当 Vitest 遇到 include 列表中指定的外部库时，它将使用 esbuild 将其打包成一个单独的文件，并作为一个完整的模块导入。这有几个好处：

• 导入具有大量导入的包的成本很高。通过将它们捆绑到一个文件中，我们可以节省大量时间。
• 导入 UI 库的成本很高，因为它们并非旨在在 Node.js 中运行。
• 你的 alias 配置现在对捆绑包生效。
• 你的测试代码的运行方式将更接近于在浏览器中的运行方式。

请注意，只有在 deps.optimizer?.[mode].include 选项中列出的包会被捆绑（某些插件会自动填充此选项，例如 Svelte）。你可以在 Vite 文档中阅读有关可用选项的更多信息（Vitest 不支持 disable 和 noDiscovery 选项）。默认情况下，Vitest 对 jsdom 和 happy-dom 环境使用 optimizer.web，对 node 和 edge 环境使用 optimizer.ssr，但它可以通过 transformMode 进行配置。

此选项还会继承你的 optimizeDeps 配置（对于 web，Vitest 将扩展 optimizeDeps，对于 SSR，则扩展 ssr.optimizeDeps）。如果在 deps.optimizer 中重新定义 include/exclude 选项，它将在运行测试时扩展你的 optimizeDeps 配置。如果 Vitest 在 exclude 中列出了相同的选项，它会自动从 include 中删除它们。

TIP

你将无法编辑 node_modules 中的代码进行调试，因为该代码实际上位于你的 cacheDir 或 test.cache.dir 目录中。如需使用 console.log 调试，请直接编辑代码或使用 deps.optimizer?.[mode].force 选项强制重新捆绑。

deps.optimizer.{mode}.enabled

• 类型： boolean
• 默认值： false

启用依赖优化。

deps.web

• 类型： { transformAssets?, ... }

在 web 转换模式下应用于外部文件的选项。默认情况下，jsdom 和 happy-dom 使用 web 模式，而 node 和 edge 环境使用 ssr 转换模式，因此这些选项对这些环境中的文件没有影响。

通常，node_modules 中的文件是外部化的，但这些选项也会影响 server.deps.external 中的文件。

deps.web.transformAssets

• 类型： boolean
• 默认值： true

Vitest 是否应处理资源文件（.png、.svg、.jpg 等），并像 Vite 在浏览器中那样解析它们。

未指定查询时，该模块的默认导出即为资源路径。

WARNING

目前，此选项仅适用于 vmThreads 和 vmForks 池。

deps.web.transformCss

• 类型： boolean
• 默认值： true

Vitest 是否应处理 CSS（.css、.scss、.sass 等）文件，并像 Vite 在浏览器中那样解析它们。

如果通过 css 选项禁用 CSS 文件，则此选项只会抑制 ERR_UNKNOWN_FILE_EXTENSION 错误。

WARNING

目前，此选项仅适用于 vmThreads 和 vmForks 池。

deps.web.transformGlobPattern

• 类型： RegExp | RegExp[]
• 默认值： []

用于匹配需要转换的外部文件的正则表达式模式。

默认情况下，node_modules 中的文件是外部化的，并且不会转换，除非它是 CSS 或资源，并且相应的选项未被禁用。

WARNING

目前，此选项仅适用于 vmThreads 和 vmForks 池。

deps.interopDefault

• 类型： boolean
• 默认值： true

将 CJS 模块的 default 导出视为命名导出。某些依赖项仅捆绑 CJS 模块，并且在使用 import 语法而不是 require 导入包时，不使用 Node.js 可以静态分析的命名导出。在 Node 环境中使用命名导出导入此类依赖项时，你可能会看到以下错误：

import { read } from 'fs-jetpack';
         ^^^^
SyntaxError: Named export 'read' not found. The requested module 'fs-jetpack' is a CommonJS module, which may not support all module.exports as named exports.
CommonJS modules can always be imported via the default export.

Vitest 不进行静态分析，无法在运行代码之前失败，因此如果禁用此功能，你很可能会在运行测试时看到以下错误：

TypeError: createAsyncThunk is not a function
TypeError: default is not a function

默认情况下，Vitest 假定你正在使用捆绑器来绕过此问题，并且不会失败，但如果你的代码未经过处理，你可以手动禁用此行为。

deps.moduleDirectories

• 类型： string[]
• 默认值： ['node_modules']

应视为模块目录的目录列表。此配置选项会影响 vi.mock 的行为：当没有提供工厂函数，并且你正在模拟的模块路径与 moduleDirectories 中的某个值匹配时，Vitest 会尝试在项目根目录下的 __mocks__ 文件夹中查找相应的模拟实现。

此选项还会影响文件在外部化依赖项时是否应被视为模块。默认情况下，Vitest 使用原生 Node.js 导入外部模块，绕过 Vite 转换步骤。

设置此选项将覆盖默认值。如果你希望仍然搜索 node_modules 中的包，请将其与其他选项一起包含：

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    deps: {
      moduleDirectories: ['node_modules', path.resolve('../../packages')],
    },
  },
});

runner

• 类型： VitestRunnerConstructor
• 默认值： 运行测试时为 node，运行基准测试时为 benchmark

自定义测试运行器的路径。这是一个高级功能，适用于自定义库运行器。你可以在文档中阅读有关它的更多信息。

benchmark

• 类型： { include?, exclude?, ... }

运行 vitest bench 时使用的配置选项。

benchmark.include

• 类型： string[]
• 默认值： ['**/*.{bench,benchmark}.?(c|m)[jt]s?(x)']

基准测试文件的包含 glob 模式。

benchmark.exclude

• 类型： string[]
• 默认值： ['node_modules', 'dist', '.idea', '.git', '.cache']

基准测试文件的排除 glob 模式。

benchmark.includeSource

• 类型： string[]
• 默认值： []

源内基准测试文件的包含 glob 模式。此选项类似于 includeSource。

定义后，Vitest 将运行所有匹配的文件，这些文件内部包含 import.meta.vitest。

benchmark.reporters

• 类型： Arrayable<BenchmarkBuiltinReporters | Reporter>
• 默认值： 'default'

自定义报告器，用于输出。可以包含一个或多个内置报告名称、报告器实例和/或自定义报告器的路径。

benchmark.outputFile

已废弃，请使用 benchmark.outputJson。

benchmark.outputJson

• 类型： string | undefined
• 默认值： undefined

用于存储基准测试结果的文件路径，该结果可用于后续的 --compare 选项。

例如：

# 保存主分支的结果
git checkout main
vitest bench --outputJson main.json

# 切换分支并与主分支进行比较
git checkout feature
vitest bench --compare main.json

benchmark.compare

• 类型： string | undefined
• 默认值： undefined

用于与当前运行进行比较的先前基准测试结果的文件路径。

alias

• 类型： Record<string, string> | Array<{ find: string | RegExp, replacement: string, customResolver?: ResolverFunction | ResolverObject }>

在测试中运行时定义自定义别名。这些别名将与 resolve.alias 中的别名合并。

WARNING

Vitest 使用 Vite SSR 原语来运行测试，这存在某些缺陷。

1. 别名仅对内联模块（默认情况下所有源代码都会内联）直接使用 import 关键字导入的模块生效。
2. Vitest 不支持对 require 调用进行别名处理。
3. 如果你要对外部依赖项（例如，react -> preact）进行别名处理，你可能需要对实际的 node_modules 包进行别名处理，以确保其适用于外部化依赖项。Yarn 和 pnpm 支持通过 npm: 前缀进行别名处理。

globals

• 类型： boolean
• 默认值： false
• CLI： --globals, --globals=false

默认情况下，为了代码的显式性，vitest 不提供全局 API。如果你更喜欢像 Jest 一样全局使用 API，可以将 --globals 选项传递给 CLI，或在配置中添加 globals: true。

// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: true,
  },
});

为了让 TypeScript 能够识别全局 API，请将 vitest/globals 添加到 tsconfig.json 的 types 字段中。

// tsconfig.json
{
  "compilerOptions": {
    "types": ["vitest/globals"]
  }
}

如果你在项目中已经使用了 unplugin-auto-import，也可以直接使用它来自动导入这些 API。

// vitest.config.ts
import { defineConfig } from 'vitest/config';
import AutoImport from 'unplugin-auto-import/vite';

export default defineConfig({
  plugins: [
    AutoImport({
      imports: ['vitest'],
      dts: true, // 生成 TypeScript 声明
    }),
  ],
});

environment

• 类型: 'node' | 'jsdom' | 'happy-dom' | 'edge-runtime' | string
• 默认值: 'node'
• CLI: --environment=<env>

测试环境：Vitest 默认使用 Node.js 环境。对于 Web 应用程序，可以使用浏览器模拟环境，例如 jsdom 或 happy-dom。对于边缘计算函数，可以使用 edge-runtime 环境。

TIP

你也可以使用浏览器模式在浏览器中运行集成或单元测试，而无需模拟环境。

可以通过在文件顶部添加 @vitest-environment 文档块或注释，为该文件中的所有测试指定环境：

文档块风格：

/**
 * @vitest-environment jsdom
 */

test('use jsdom in this test file', () => {
  const element = document.createElement('div');
  expect(element).not.toBeNull();
});

注释风格：

// @vitest-environment happy-dom

test('use happy-dom in this test file', () => {
  const element = document.createElement('div');
  expect(element).not.toBeNull();
});

为了与 Jest 兼容，也支持 @jest-environment：

/**
 * @jest-environment jsdom
 */

test('use jsdom in this test file', () => {
  const element = document.createElement('div');
  expect(element).not.toBeNull();
});

如果使用 --isolate=false 标志运行 Vitest，测试将按照 node、jsdom、happy-dom、edge-runtime、custom environments (自定义环境) 的顺序分组运行。相同环境的测试会被分组在一起，但组内的测试仍然是顺序执行的。

从 0.23.0 开始，可以定义自定义环境。当使用非内置环境时，Vitest 会尝试加载 vitest-environment-${name} 包。该包应导出一个类型为 Environment 的对象：

import type { Environment } from 'vitest';

export default <Environment>{
  name: 'custom',
  transformMode: 'ssr',
  setup() {
    // custom setup
    return {
      teardown() {
        // called after all tests with this env have been run
      },
    };
  },
};

Vitest 还通过 vitest/environments 入口提供了 builtinEnvironments，以便扩展内置环境。更多关于扩展环境的信息，请参考 我们的指南。

TIP

jsdom 环境暴露了 jsdom 全局对象，它等于当前的 JSDOM 实例。如果希望 TypeScript 识别该类型，可以在使用此环境时将 vitest/jsdom 添加到 tsconfig.json 中：

{
  "compilerOptions": {
    "types": ["vitest/jsdom"]
  }
}

environmentOptions

• 类型: Record<'jsdom' | string, unknown>
• 默认值: {}

这些选项会传递给当前 environment 的 setup 方法。默认情况下，如果使用 JSDOM 作为测试环境，则只能配置 JSDOM 选项。

environmentMatchGlobs

• 类型: [string, EnvironmentName][]
• 默认值: []

根据 glob 自动指定环境。使用第一个匹配项。

例如：

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environmentMatchGlobs: [
      // all tests in tests/dom will run in jsdom
      ['tests/dom/**', 'jsdom'],
      // all tests in tests/ with .edge.test.ts will run in edge-runtime
      ['**/*.edge.test.ts', 'edge-runtime'],
      // ...
    ],
  },
});

poolMatchGlobs

• 类型: [string, 'threads' | 'forks' | 'vmThreads' | 'vmForks' | 'typescript'][]
• 默认值: []

根据 glob 自动分配测试运行的线程池 (pool)。使用第一个匹配项。

例如：

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolMatchGlobs: [
      // all tests in "worker-specific" directory will run inside a worker as if you enabled `--pool=threads` for them,
      ['**/tests/worker-specific/**', 'threads'],
      // run all tests in "browser" directory in an actual browser
      ['**/tests/browser/**', 'browser'],
      // all other tests will run based on "browser.enabled" and "threads" options, if you didn't specify other globs
      // ...
    ],
  },
});

update*

• 类型: boolean
• 默认值: false
• CLI: -u, --update, --update=false

更新快照文件。这将更新所有已更改的快照，并删除过期的快照。

watch*

• 类型: boolean
• 默认值: !process.env.CI
• CLI: -w, --watch, --watch=false

启用监听模式。

root

• 类型: string
• CLI: -r <path>, --root=<path>

项目根目录。

dir

• 类型： string
• 命令行： --dir=<path>
• 默认值： 同 root

扫描测试文件的基本目录。如果你的根目录覆盖了整个项目，你可以指定此选项来加快测试发现的速度。

reporters*

• 类型: Reporter | Reporter[]
• 默认值: 'default'
• CLI: --reporter=<name>, --reporter=<name1> --reporter=<name2>

自定义 报告器 用于输出测试结果。报告器可以是 一个 Reporter 实例、一个用于选择内置测试报告器的字符串，或者一个指向自定义实现的路径 (例如 './path/to/reporter.ts', '@scope/reporter')。

outputFile*

• 类型: string | Record<string, string>
• CLI: --outputFile=<path>, --outputFile.json=./path

当同时指定 --reporter=json、--reporter=html 或 --reporter=junit 选项时，将测试结果输出到文件。 通过提供一个对象而不是字符串，可以在使用多个测试报告器时定义单独的输出路径。

pool*

• 类型: 'threads' | 'forks' | 'vmThreads' | 'vmForks'
• 默认值: 'forks'
• CLI: --pool=threads

用于运行测试的进程池。

threads*

启用多线程，使用 tinypool（Piscina 的轻量级分叉）。使用线程时，无法使用与进程相关的 API，例如 process.chdir()。一些使用原生语言编写的库，例如 Prisma、bcrypt 和 canvas，在多线程中运行时可能会出现问题并导致段错误。在这些情况下，建议使用 forks 进程池代替。

forks*

与 threads 进程池类似，但通过 tinypool 使用 child_process (子进程) 而不是 worker_threads。测试和主进程之间的通信速度不如 threads 进程池。与进程相关的 API，例如 process.chdir() 在 forks 进程池中可用。

vmThreads*

在 threads 进程池中使用 VM 上下文 (在沙箱环境中) 运行测试。

这使得测试运行速度更快，但当运行 ESM 代码时，VM 模块可能不稳定。测试可能会发生内存泄漏，为了解决这个问题，可以考虑手动编辑 poolOptions.vmThreads.memoryLimit 的值。

WARNING

在沙箱中运行代码有一些优点（更快的测试），但也带来了一些缺点。

• 原生模块中的全局变量 (例如 fs、path 等) 与测试环境中存在的全局变量不同。因此，这些原生模块抛出的任何错误都会引用与代码中使用的错误构造函数不同的错误构造函数：

try {
  fs.writeFileSync('/doesnt exist');
} catch (err) {
  console.log(err instanceof Error); // false
}

• 导入 ES 模块会永久缓存它们，如果你有很多上下文（测试文件），这会导致内存泄漏。Node.js 中没有清除该缓存的 API。
• 在沙箱环境中访问全局变量 需要更长的时间。

在使用此选项时，请注意这些问题。Vitest 团队无法在我们这边修复任何问题。

vmForks*

与 vmThreads 进程池类似，但通过 tinypool 使用 child_process (子进程) 而不是 worker_threads。测试和主进程之间的通信速度不如 vmThreads 进程池。与进程相关的 API，例如 process.chdir() 在 vmForks 进程池中可用。请注意，此进程池具有 vmThreads 中列出的相同缺陷。

poolOptions*

• 类型: Record<'threads' | 'forks' | 'vmThreads' | 'vmForks', {}>
• 默认值: {}

poolOptions.threads

threads 池的选项。

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolOptions: {
      threads: {
        // Threads related options here
      },
    },
  },
});

poolOptions.threads.maxThreads*

• 类型： number | string
• 默认值： 可用 CPU 数量

线程的最大数量或百分比。您也可以使用环境变量 VITEST_MAX_THREADS。

poolOptions.threads.minThreads*

• 类型： number | string
• 默认值： 可用 CPU 数量

线程的最小数量或百分比。您也可以使用环境变量 VITEST_MIN_THREADS。

poolOptions.threads.singleThread

• 类型: boolean
• 默认值: false

在单个 worker 线程中运行具有相同环境的所有测试。这将禁用内置的模块隔离（你的源代码或 内联 代码仍将为每个测试重新评估），但可以提高测试性能。

WARNING

即使此选项会强制测试串行运行，它也与 Jest 的 --runInBand 不同。Vitest 使用 worker 不仅用于并行运行测试，还用于提供隔离。禁用此选项后，测试会按顺序运行，但在相同的全局上下文中运行，因此需要自行提供隔离。

如果你依赖于全局状态（前端框架通常这样做）或者你的代码依赖于为每个测试单独定义的环境，这可能会导致各种问题。但是，对于那些不一定依赖于全局状态或可以轻松绕过它的测试来说，这可以提高测试速度（最多快 3 倍）。

poolOptions.threads.useAtomics*

• 类型: boolean
• 默认值: false

使用 Atomics 来同步线程。

这可以在某些情况下提高性能，但可能会在较旧的 Node 版本中导致段错误。

poolOptions.threads.isolate

• 类型: boolean
• 默认值: true

为每个测试文件隔离环境。

poolOptions.threads.execArgv*

• 类型: string[]
• 默认值: []

在线程中将其他参数传递给 node。有关更多信息，请参见 命令行 API | Node.js。

WARNING

使用时请小心，因为某些选项可能会导致 worker 崩溃，例如 --prof, --title。请参见 https://github.com/nodejs/node/issues/41103。

poolOptions.forks

forks 池的选项。

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolOptions: {
      forks: {
        // Forks related options here
      },
    },
  },
});

poolOptions.forks.maxForks*

• 类型: number | string
• 默认值: 可用 CPU 数量

最大进程数或百分比。

poolOptions.forks.minForks*

• 类型: number | string
• 默认值: 可用 CPU 数量

最小进程数或百分比。

poolOptions.forks.isolate

• 类型: boolean
• 默认值: true

为每个测试文件隔离环境。

poolOptions.forks.singleFork

• 类型: boolean
• 默认值: false

在单个子进程中运行具有相同环境的所有测试。这将禁用内置的模块隔离（你的源代码或 内联 代码仍将为每个测试重新评估），但可以提高测试性能。

WARNING

即使此选项会强制测试串行运行，它也与 Jest 的 --runInBand 不同。Vitest 使用子进程不仅用于并行运行测试，还用于提供隔离。禁用此选项后，测试会按顺序运行，但在相同的全局上下文中运行，因此需要自行提供隔离。

如果你依赖于全局状态（前端框架通常这样做）或者你的代码依赖于为每个测试单独定义的环境，这可能会导致各种问题。但是，对于那些不一定依赖于全局状态或可以轻松绕过它的测试来说，这可以提高测试速度（最多快 3 倍）。

poolOptions.forks.execArgv*

• 类型: string[]
• 默认值: []

在子进程中将其他参数传递给 node 进程。有关更多信息，请参见 命令行 API | Node.js。

WARNING

使用时请小心，因为某些选项可能会导致 worker 崩溃，例如 --prof, --title。请参见 https://github.com/nodejs/node/issues/41103。

poolOptions.vmThreads

vmThreads 池的选项。

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolOptions: {
      vmThreads: {
        // VM threads related options here
      },
    },
  },
});

poolOptions.vmThreads.maxThreads*

• 类型: number | string
• 默认值: 可用 CPU 核心数

线程的最大数量或百分比。你也可以使用 VITEST_MAX_THREADS 环境变量。

poolOptions.vmThreads.minThreads*

• 类型: number | string
• 默认值: 可用 CPU 核心数

线程的最小数量或百分比。你也可以使用 VITEST_MIN_THREADS 环境变量。

poolOptions.vmThreads.memoryLimit*

• 类型: string | number
• 默认值: 1 / CPU Cores

指定回收 worker 之前的内存限制。此值在很大程度上取决于你的环境，因此最好手动指定它，而不是依赖默认值。该限制可以通过多种不同的方式指定，最终都会使用 Math.floor 将其转换为整数值：

• <= 1 - 该值被假定为系统内存的百分比。因此，0.5 将 worker 的内存限制设置为总系统内存的一半

• \> 1 - 假定为固定字节值。由于之前的规则，如果你想要 1 字节的值（我不知道为什么），你可以使用 1.1。

• 带单位

  • 50% - 如上所述，占总系统内存的百分比

  • 100KB, 65MB 等 - 带有单位表示固定内存限制。

    • K / KB - 千字节 (x1000)、
    • KiB - 千比字节 (x1024)、
    • M / MB - 兆字节、
    • MiB - 兆比字节、
    • G / GB - 吉字节、
    • GiB - 吉比字节

:::

WARNING

由于报告的系统内存不正确，基于百分比的内存限制 在 Linux CircleCI 上不起作用 worker。

poolOptions.vmThreads.useAtomics*

• 类型: boolean
• 默认值: false

使用 Atomics 来同步线程。

这可以在某些情况下提高性能，但可能会在较旧的 Node 版本中导致段错误。

poolOptions.vmThreads.execArgv*

• 类型: string[]
• 默认值: []

在 VM 上下文中将其他参数传递给 node 进程。有关更多信息，请参见 命令行 API | Node.js。

WARNING

使用时请小心，因为某些选项可能会导致 worker 崩溃，例如 --prof, --title。请参见 https://github.com/nodejs/node/issues/41103。

poolOptions.vmForks

vmForks 池的选项。

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolOptions: {
      vmForks: {
        // VM forks related options here
      },
    },
  },
});

poolOptions.vmForks.maxForks*

• 类型: number | string
• 默认值: 可用 CPU 数量

最大线程数或线程百分比。您也可以使用 VITEST_MAX_FORKS 环境变量。

poolOptions.vmForks.minForks*

• 类型: number | string
• 默认值: 可用 CPU 数量

最小线程数或线程百分比。您也可以使用 VITEST_MIN_FORKS 环境变量。

poolOptions.vmForks.memoryLimit*

• 类型: string | number
• 默认值: 1 / CPU Cores

指定回收 worker 之前的内存限制。此值在很大程度上取决于你的环境，因此最好手动指定它，而不是依赖默认值。该值的计算方式请参考 poolOptions.vmThreads.memoryLimit 中的描述。

poolOptions.vmForks.execArgv*

• 类型: string[]
• 默认值: []

在 VM 上下文中将其他参数传递给 node 进程。有关更多信息，请参见 命令行 API | Node.js。

WARNING

使用时请小心，因为某些选项可能会导致 worker 崩溃，例如 --prof, --title。请参见 https://github.com/nodejs/node/issues/41103。

fileParallelism*

• 类型: boolean
• 默认值: true
• CLI: --no-file-parallelism, --fileParallelism=false

是否并行运行所有测试文件。设置为 false 会将 maxWorkers 和 minWorkers 选项强制设置为 1。

TIP

此选项不影响同一文件中的测试用例的并行运行。 如需并行运行同一文件中的测试用例，请在 describe 块上使用 concurrent 选项（参见 API 文档），或通过 配置 进行设置。

maxWorkers*

• Type: number | string

运行测试的最大工作线程数。poolOptions.{threads,vmThreads}.maxThreads/poolOptions.forks.maxForks 优先级更高。

minWorkers*

• Type: number | string

运行测试的最小工作线程数或百分比。poolOptions.{threads,vmThreads}.minThreads/poolOptions.forks.minForks 优先级更高。

testTimeout

• Type: number
• Default: Node.js 中为 5_000，如果 browser.enabled 为 true 则为 15_000。
• CLI: --test-timeout=5000, --testTimeout=5000

测试的默认超时时间（毫秒）

hookTimeout

• Type: number
• Default: Node.js 中为 10_000，如果 browser.enabled 为 true 则为 30_000。
• CLI: --hook-timeout=10000, --hookTimeout=10000

钩子的默认超时时间（毫秒）

teardownTimeout*

• 类型: number
• 默认值: 10000
• CLI: --teardown-timeout=5000, --teardownTimeout=5000

Vitest 关闭时，等待所有清理任务完成的默认超时时间，单位为毫秒。

silent*

• 类型: boolean
• 默认值: false
• CLI: --silent, --silent=false

禁止测试过程中的控制台输出。

setupFiles

• 类型: string | string[]

配置文件路径。这些文件会在每个测试文件运行之前执行。

INFO

编辑 setup 文件将自动触发所有测试的重新运行。

您可以在这些文件中使用 process.env.VITEST_POOL_ID (一个类似整数的字符串) 来区分不同的工作进程。

TIP

注意：当运行 --isolate=false 时，这些设置文件会在同一个全局作用域中多次运行。这意味着每次测试前都会访问相同的全局对象，请确保你的代码不会产生副作用。

例如，您可以依赖一个全局变量：

import { config } from '@some-testing-lib';

if (!globalThis.defined) {
  config.plugins = [myCoolPlugin];
  computeHeavyThing();
  globalThis.defined = true;
}

// hooks are reset before each suite
afterEach(() => {
  cleanup();
});

globalThis.resetBeforeEachTest = true;

provide 2.1.0+

• Type: Partial<ProvidedContext>

使用 inject 方法定义可以在测试中访问的值。

vitest.config.js

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    provide: {
      API_KEY: '123',
    },
  },
});

my.test.js

import { expect, inject, test } from 'vitest';

test('api key is defined', () => {
  expect(inject('API_KEY')).toBe('123');
});

WARNING

属性必须是字符串，并且值需要是 可序列化的，因为此对象将在不同进程之间传输。

TIP

如果您使用 TypeScript，您将需要扩充 ProvidedContext 类型以进行类型安全访问：

// vitest.shims.d.ts

declare module 'vitest' {
  export interface ProvidedContext {
    API_KEY: string;
  }
}

// mark this file as a module so augmentation works correctly
export {};

globalSetup

• 类型: string | string[]

全局配置文件路径（相对于项目根目录）。

全局配置文件可以导出命名函数 setup 和 teardown，或者导出一个返回 teardown 函数的 default 函数（示例）。

INFO

支持多个全局配置文件。 setup 函数按顺序执行，teardown 函数按相反顺序执行。

WARNING

全局 setup 仅在至少有一个正在运行的测试时才会运行。这意味着全局 setup 可能会在监视模式下，在测试文件更改后开始运行（测试文件将等待全局 setup 完成后再运行）。

注意，全局 setup 运行在不同的全局作用域中，因此你的测试无法访问此处定义的变量。但是，你可以通过 provide 方法将可序列化的数据传递给测试：

globalSetup.js

export default function setup({ provide }) {
  provide('wsPort', 3000);
}

globalSetup.ts

import type { GlobalSetupContext } from 'vitest/node';

export default function setup({ provide }: GlobalSetupContext) {
  provide('wsPort', 3000);
}

declare module 'vitest' {
  export interface ProvidedContext {
    wsPort: number;
  }
}

example.test.js

import { inject } from 'vitest';

inject('wsPort') === 3000;

forceRerunTriggers*

• 类型: string[]
• 默认值: ['**/package.json/**', '**/vitest.config.*/**', '**/vite.config.*/**']

指定的文件路径 glob 模式，这些文件路径的更改会触发整个测试套件重新运行。当配合 --changed 参数使用时，如果在 git diff 中发现匹配的文件，则运行整个测试套件。

适用于测试 CLI 命令调用，因为 Vite 无法构建模块依赖图：

test('execute a script', async () => {
  // 如果 `dist/index.js` 的内容发生更改，Vitest 无法重新运行此测试
  await execa('node', ['dist/index.js']);
});

TIP

确保这些文件没有被 server.watch.ignored 排除。

coverage*

支持使用 v8、istanbul 或 自定义覆盖率解决方案 来收集代码覆盖率。

可以通过点表示法向 CLI 传递覆盖率选项：

npx vitest --coverage.enabled --coverage.provider=istanbul --coverage.all

WARNING

使用点表示法的覆盖率选项时，必须指定 --coverage.enabled。 此时不应单独使用 --coverage 选项。

coverage.provider

• 类型: 'v8' | 'istanbul' | 'custom'
• 默认值: 'v8'
• CLI: --coverage.provider=<provider>

使用指定的 provider 来收集代码覆盖率。

coverage.enabled

• 类型: boolean
• 默认值: false
• 适用 providers: 'v8' | 'istanbul'
• CLI: --coverage.enabled, --coverage.enabled=false

启用代码覆盖率收集功能。可以通过 --coverage CLI 选项覆盖此设置。

coverage.include

• 类型: string[]
• 默认值: ['**']
• 适用 providers: 'v8' | 'istanbul'
• CLI: --coverage.include=<path>, --coverage.include=<path1> --coverage.include=<path2>

指定需要纳入代码覆盖率统计的文件 glob 模式列表。

coverage.extension

• 类型: string | string[]
• 默认值: ['.js', '.cjs', '.mjs', '.ts', '.mts', '.tsx', '.jsx', '.vue', '.svelte', '.marko', '.astro']
• 适用 providers: 'v8' | 'istanbul'
• CLI: --coverage.extension=<extension>, --coverage.extension=<extension1> --coverage.extension=<extension2>

指定需要纳入代码覆盖率统计的文件扩展名。

coverage.exclude

• 类型: string[]
• 默认值:

[
  'coverage/**',
  'dist/**',
  '**/node_modules/**',
  '**/[.]**',
  'packages/*/test?(s)/**',
  '**/*.d.ts',
  '**/virtual:*',
  '**/__x00__*',
  '**/\x00*',
  'cypress/**',
  'test?(s)/**',
  'test?(-*).?(c|m)[jt]s?(x)',
  '**/*{.,-}{test,spec,bench,benchmark}?(-d).?(c|m)[jt]s?(x)',
  '**/__tests__/**',
  '**/{karma,rollup,webpack,vite,vitest,jest,ava,babel,nyc,cypress,tsup,build,eslint,prettier}.config.*',
  '**/vitest.{workspace,projects}.[jt]s?(on)',
  '**/.{eslint,mocha,prettier}rc.{?(c|m)js,yml}',
];

• 适用 providers: 'v8' | 'istanbul'
• CLI: --coverage.exclude=<path>, --coverage.exclude=<path1> --coverage.exclude=<path2>

指定需要排除在代码覆盖率统计之外的文件 glob 模式列表。

此选项会覆盖所有默认配置。添加新的忽略模式时，需要扩展默认选项：

import { coverageConfigDefaults, defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    coverage: {
      exclude: ['**/custom-pattern/**', ...coverageConfigDefaults.exclude],
    },
  },
});

注意

Vitest 会自动将测试文件 include 模式添加到 coverage.exclude 的默认值中。

coverage.all

• 类型: boolean
• 默认值: true
• 适用 providers: 'v8' | 'istanbul'
• CLI: --coverage.all, --coverage.all=false

是否将所有文件（包括未被测试的文件）都纳入覆盖率报告。

coverage.clean

• 类型: boolean
• 默认值: true
• 适用 providers: 'v8' | 'istanbul'
• CLI: --coverage.clean, --coverage.clean=false

在运行测试之前清除之前的覆盖率结果。

coverage.cleanOnRerun

• 类型: boolean
• 默认值: true
• 适用 providers: 'v8' | 'istanbul'
• CLI: --coverage.cleanOnRerun, --coverage.cleanOnRerun=false

在监视模式重新运行时清除代码覆盖率报告。设置为 false 以保留监视模式之前运行的代码覆盖率结果。

coverage.reportsDirectory

• 类型: string
• 默认值: './coverage'
• 适用 providers: 'v8' | 'istanbul'
• CLI: --coverage.reportsDirectory=<path>

WARNING

如果启用了 coverage.clean（默认值），Vitest 将在运行测试之前删除此目录。

覆盖率报告的输出目录。

在 HTML 报告器 输出中预览覆盖率报告时，需要将此选项设置为 HTML 报告目录的子目录（例如 ./html/coverage）。

coverage.reporter

• 类型: string | string[] | [string, {}][]
• 默认值: ['text', 'html', 'clover', 'json']
• 适用 providers: 'v8' | 'istanbul'
• CLI: --coverage.reporter=<reporter>, --coverage.reporter=<reporter1> --coverage.reporter=<reporter2>

使用的覆盖率报告器。所有报告器详见 istanbul 文档。有关报告器特定选项的详细信息，请参见 @types/istanbul-reporter。

报告器支持三种类型：

• 单一报告器：{ reporter: 'html' }
• 无配置的多报告器：{ reporter: ['html', 'json'] }
• 带配置的单/多报告器：

  {
    reporter: [
      ['lcov', { projectRoot: './src' }],
      ['json', { file: 'coverage.json' }],
      ['text'],
    ];
  }

您也可以传递自定义覆盖率报告器。有关更多信息，请参阅指南 - 自定义覆盖率报告器。

{
  reporter: [
    // Specify reporter using name of the NPM package
    '@vitest/custom-coverage-reporter',
    ['@vitest/custom-coverage-reporter', { someOption: true }],

    // Specify reporter using local path
    '/absolute/path/to/custom-reporter.cjs',
    ['/absolute/path/to/custom-reporter.cjs', { someOption: true }],
  ];
}

你可以在 Vitest UI 中查看你的覆盖率报告：查看 Vitest UI 覆盖率 获取更多详情。

coverage.reportOnFailure

• 类型: boolean
• 默认值: false
• 适用 providers: 'v8' | 'istanbul'
• CLI: --coverage.reportOnFailure, --coverage.reportOnFailure=false

即使测试失败，也生成覆盖率报告。

coverage.allowExternal

• 类型: boolean
• 默认值: false
• 适用 providers: 'v8' | 'istanbul'
• CLI: --coverage.allowExternal, --coverage.allowExternal=false

收集项目根目录 root 之外的文件的覆盖率。

coverage.excludeAfterRemap 2.1.0+

• 类型： boolean
• 默认值： false
• 可用 providers： 'v8' | 'istanbul'
• CLI： --coverage.excludeAfterRemap, --coverage.excludeAfterRemap=false

在 coverage 重新映射到原始源文件后再次应用排除规则。 当你的源文件经过转译并且可能包含非源文件的 source map 时，此选项很有用。

当你在报告中看到即使与你的 coverage.exclude 模式匹配的文件仍然出现时，请使用此选项。

coverage.skipFull

• 类型: boolean
• 默认值: false
• 适用 providers: 'v8' | 'istanbul'
• CLI: --coverage.skipFull, --coverage.skipFull=false

隐藏语句/分支/函数覆盖率达到 100% 的文件。

coverage.thresholds

覆盖率阈值选项。

coverage.thresholds.lines

• 类型: number
• 适用 providers: 'v8' | 'istanbul'
• CLI: --coverage.thresholds.lines=<number>

行覆盖率的全局阈值。 详见 istanbul 文档。

coverage.thresholds.functions

• 类型: number
• 适用 providers: 'v8' | 'istanbul'
• CLI: --coverage.thresholds.functions=<number>

函数覆盖率的全局阈值。 详见 istanbul 文档。

coverage.thresholds.branches

• 类型: number
• 适用 providers: 'v8' | 'istanbul'
• CLI: --coverage.thresholds.branches=<number>

分支覆盖率的全局阈值。 详见 istanbul 文档。

coverage.thresholds.statements

• 类型: number
• 适用 providers: 'v8' | 'istanbul'
• CLI: --coverage.thresholds.statements=<number>

语句覆盖率的全局阈值。 详见 istanbul 文档。

coverage.thresholds.perFile

• 类型: boolean
• 默认值: false
• 适用 providers: 'v8' | 'istanbul'
• CLI: --coverage.thresholds.perFile, --coverage.thresholds.perFile=false

按文件检查覆盖率阈值。

coverage.thresholds.autoUpdate

• 类型: boolean
• 默认值: false
• 适用 providers: 'v8' | 'istanbul'
• CLI: --coverage.thresholds.autoUpdate=<boolean>

当当前覆盖率高于配置的阈值时，自动将所有阈值（lines、functions、branches 和 statements）更新到配置文件。 覆盖率提升时，可以帮助维护阈值。

coverage.thresholds.100

• 类型: boolean
• 默认值: false
• 适用 providers: 'v8' | 'istanbul'
• CLI: --coverage.thresholds.100, --coverage.thresholds.100=false

设置全局阈值为 100%。 相当于 --coverage.thresholds.lines 100 --coverage.thresholds.functions 100 --coverage.thresholds.branches 100 --coverage.thresholds.statements 100。

coverage.thresholds[glob-pattern]

• 类型: { statements?: number functions?: number branches?: number lines?: number }
• 默认值: undefined
• 适用 providers: 'v8' | 'istanbul'

为匹配指定 glob 模式的文件设置覆盖率阈值。

注意

Vitest 会将所有文件（包括那些被 glob 模式覆盖的文件）都计入全局覆盖率阈值。这与 Jest 的行为不同。

{
  coverage: {
    thresholds: {
      // Thresholds for all files
      functions: 95,
      branches: 70,

      // Thresholds for matching glob pattern
      'src/utils/**.ts': {
        statements: 95,
        functions: 90,
        branches: 85,
        lines: 80,
      },

      // Files matching this pattern will only have lines thresholds set.
      // Global thresholds are not inherited.
      '**/math.ts': {
        lines: 100,
      }
    }
  }
}

coverage.thresholds[glob-pattern].100 2.1.0+

• 类型: boolean
• 默认: false
• 适用于 providers: 'v8' | 'istanbul'

为匹配 glob 模式的文件设置阈值为 100。

{
  coverage: {
    thresholds: {
      // 所有文件的阈值
      functions: 95,
      branches: 70,

      // 匹配 glob 模式的文件的阈值
      'src/utils/**.ts': { 100: true },
      '**/math.ts': { 100: true }
    }
  }
}

coverage.ignoreEmptyLines

• 类型: boolean
• 默认值: true (v1 中为 false)
• 适用 providers: 'v8'
• CLI: --coverage.ignoreEmptyLines=<boolean>

忽略空行、注释以及非运行时代码（如 TypeScript 类型）。

仅当编译器从转译代码中移除注释和非运行时代码时有效。 默认情况下，Vite 使用 ESBuild 从 .ts、.tsx 和 .jsx 文件中移除注释和 TypeScript 类型。

如需将 ESBuild 应用于其他文件，请在 esbuild 选项 中定义它们：

import { defineConfig } from 'vitest/config';

export default defineConfig({
  esbuild: {
    // Transpile all files with ESBuild to remove comments from code coverage.
    // Required for `test.coverage.ignoreEmptyLines` to work:
    include: ['**/*.js', '**/*.jsx', '**/*.mjs', '**/*.ts', '**/*.tsx'],
  },
  test: {
    coverage: {
      provider: 'v8',
      ignoreEmptyLines: true,
    },
  },
});

coverage.ignoreClassMethods

• 类型: string[]
• 默认值: []
• 适用 providers: 'istanbul'
• CLI: --coverage.ignoreClassMethods=<method>

设置为要忽略覆盖率的类方法名称的数组。 有关更多信息，请参见 istanbul 文档。

coverage.watermarks

• 类型:

{
  statements?: [number, number],
  functions?: [number, number],
  branches?: [number, number],
  lines?: [number, number]
}

• 默认值:

{
  statements: [50, 80],
  functions: [50, 80],
  branches: [50, 80],
  lines: [50, 80]
}

• 适用 providers: 'v8' | 'istanbul'
• CLI: --coverage.watermarks.statements=50,80, --coverage.watermarks.branches=50,80

语句、行、分支和函数的水印。 有关更多信息，请参见 istanbul 文档。

coverage.processingConcurrency

• 类型: boolean
• 默认值: Math.min(20, os.availableParallelism?.() ?? os.cpus().length)
• 适用 providers: 'v8' | 'istanbul'
• CLI: --coverage.processingConcurrency=<number>

处理覆盖率结果时使用的并发数限制。

coverage.customProviderModule

• 类型: string
• 适用 providers: 'custom'
• CLI: --coverage.customProviderModule=<path or module name>

指定自定义覆盖率提供程序模块的名称或路径。 有关更多信息，请参见 指南 - 自定义覆盖率提供程序。

testNamePattern*

• 类型 string | RegExp
• CLI: -t <pattern>, --testNamePattern=<pattern>, --test-name-pattern=<pattern>

运行名称与该模式完全匹配的测试。 如果设置了此属性，则测试名称中不包含该模式的测试将会被跳过。

import { expect, test } from 'vitest';

// 运行
test('OnlyRunThis', () => {
  expect(true).toBe(true);
});

// 跳过
test('doNotRun', () => {
  expect(true).toBe(true);
});

open*

• 类型: boolean
• 默认值: !process.env.CI
• CLI: --open, --open=false

打开 Vitest UI（开发中）。

api

• 类型: boolean | number
• 默认值: false
• CLI: --api, --api.port, --api.host, --api.strictPort

监听端口并启动 API 服务。设置为 true 时，默认端口为 51204。

browser

• 类型: { enabled?, name?, provider?, headless?, api? }
• 默认值: { enabled: false, headless: process.env.CI, api: 63315 }
• CLI: --browser, --browser=<name>, --browser.name=chrome --browser.headless

在浏览器中运行 Vitest 测试。默认情况下，我们使用 WebdriverIO 运行测试，但可以使用 browser.provider 选项进行配置。

NOTE

请阅读 指南 了解更多关于在真实浏览器中进行测试的信息。

WARNING

这是一个实验性功能。重大变更可能不遵循 SemVer 规范，使用时请锁定 Vitest 的版本。

browser.enabled

• 类型: boolean
• 默认值: false
• CLI: --browser, --browser.enabled=false

默认情况下在浏览器中运行所有测试。可通过 poolMatchGlobs 选项覆盖。

browser.name

• 类型: string
• CLI: --browser=safari

在指定的浏览器中运行所有测试。不同 provider 支持的选项：

• webdriverio: firefox, chrome, edge, safari
• playwright: firefox, webkit, chromium
• custom: 任何将传递给 provider 的字符串

browser.headless

• 类型: boolean
• 默认值: process.env.CI
• CLI: --browser.headless, --browser.headless=false

以 headless 模式运行浏览器。如果在 CI 环境中运行 Vitest，则默认启用。

browser.isolate

• 类型: boolean
• 默认值: true
• CLI: --browser.isolate, --browser.isolate=false

在单独的 iframe 中运行每个测试。

browser.testerHtmlPath

• 类型： string
• 默认值： @vitest/browser/tester.html
• 版本： Vitest 2.1.4 起可用

HTML 入口文件的路径。可以是项目根目录的相对路径。该文件将通过 transformIndexHtml 钩子进行处理。

browser.api

• 类型： number | { port?, strictPort?, host? }
• 默认值： 63315
• CLI： --browser.api=63315、--browser.api.port=1234, --browser.api.host=example.com

配置 Vite 服务器的选项，该服务器在浏览器中提供代码。不影响 test.api 选项。默认情况下，Vitest 分配端口 63315 以避免与开发服务器冲突，允许您并行运行两者。

browser.provider

• 类型： 'webdriverio' | 'playwright' | 'preview' | string
• 默认值： 'preview'
• CLI： --browser.provider=playwright

用于运行浏览器测试的提供程序路径。Vitest 提供三个提供程序：preview（默认）、webdriverio 和 playwright。自定义提供程序应使用 default 导出，并具有以下形状：

export interface BrowserProvider {
  name: string;
  getSupportedBrowsers: () => readonly string[];
  initialize: (
    ctx: Vitest,
    options: { browser: string; options?: BrowserProviderOptions }
  ) => Awaitable<void>;
  openPage: (url: string) => Awaitable<void>;
  close: () => Awaitable<void>;
}

WARNING

这是一个面向库作者的高级 API。如果您只需要在浏览器中运行测试，请使用 browser 选项。

browser.providerOptions

• 类型: BrowserProviderOptions

调用 provider.initialize 时传递给 provider 的选项。

export default defineConfig({
  test: {
    browser: {
      providerOptions: {
        launch: {
          devtools: true,
        },
      },
    },
  },
});

TIP

为了在使用内置 provider 时获得更好的类型安全，您可以将以下类型之一（对应您使用的 provider）添加到 tsconfig 的 compilerOptions.types 字段中：

{
  "compilerOptions": {
    "types": [
      "@vitest/browser/providers/webdriverio",
      "@vitest/browser/providers/playwright"
    ]
  }
}

browser.ui

• 类型： boolean
• 默认值： !isCI
• CLI： --browser.ui=false

是否应将 Vitest UI 注入页面。默认情况下，在开发期间注入 UI iframe。

browser.viewport

• 类型： { width, height }
• 默认值： 414x896

默认 iframe 的视口。

browser.locators

内置 浏览器定位器 的选项。

browser.locators.testIdAttribute

• 类型： string
• 默认值： data-testid

用于查找具有 getByTestId 定位器的元素的属性。

browser.screenshotDirectory

• 类型： string
• 默认值： 测试文件目录中的 __snapshots__

相对于 root 的快照目录路径。

browser.screenshotFailures

• 类型： boolean
• 默认值： !browser.ui

测试失败时 Vitest 是否应截屏。

browser.orchestratorScripts

• 类型： BrowserScript[]
• 默认值： []

应在测试 iframe 启动之前注入到 orchestrator HTML 中的自定义脚本。此 HTML 文档仅设置 iframe，实际上不导入您的代码。

脚本 src 和 content 将由 Vite 插件处理。脚本应符合以下类型定义：

export interface BrowserScript {
  /**
   * 如果提供了 "content" 且类型为 "module"，这将作为它的标识符。
   *
   * 如果您使用的是 TypeScript，则可以在此处添加 `.ts` 扩展名，例如。
   * @default `injected-${index}.js`
   */
  id?: string;
  /**
   * 要注入的 JavaScript 内容。如果类型为 "module"，则此字符串由 Vite 插件处理。
   *
   * 您可以使用 `id` 为 Vite 提供有关文件扩展名的提示。
   */
  content?: string;
  /**
   * 脚本的路径。此值由 Vite 解析，因此它可以是 node 模块或文件路径。
   */
  src?: string;
  /**
   * 脚本是否应异步加载。
   */
  async?: boolean;
  /**
   * 脚本类型。
   * @default 'module'
   */
  type?: string;
}

browser.testerScripts

• 类型: BrowserScript[]
• 默认值: []

在启动测试环境之前，注入到测试器 HTML 中的自定义脚本。这对于注入 Vitest 浏览器实现所需的 polyfill 非常有用。建议在几乎所有情况下都使用 setupFiles 而不是此选项。

脚本 src 和 content 将由 Vite 插件处理。

browser.commands

• 类型： Record<string, BrowserCommand>
• 默认值： { readFile, writeFile, ... }

可以在浏览器测试期间从 @vitest/browser/commands 导入的自定义命令。

clearMocks

• 类型: boolean
• 默认值: false

将在每个测试之前对所有 spies 调用 .mockClear()。这将清除模拟调用记录，但不会将其实现重置为默认实现。

mockReset

• 类型: boolean
• 默认值: false

将在每个测试之前对所有 spies 调用 .mockReset()。这将清除模拟调用记录并将其实现重置为空函数（将返回 undefined）。

restoreMocks

• 类型: boolean
• 默认值: false

将在每个测试之前对所有 spies 调用 .mockRestore()。这将清除模拟调用记录并将其实现重置为原始实现。

unstubEnvs

• 类型: boolean
• 默认值: false

将在每个测试之前调用 vi.unstubAllEnvs。

unstubGlobals

• 类型: boolean
• 默认值: false

将在每个测试之前调用 vi.unstubAllGlobals。

testTransformMode

• 类型: { web?, ssr? }

确定与 glob 模式匹配的测试中导入的模块的转换方式。默认情况下，取决于运行环境。例如，具有 JSDOM 环境的测试将使用 ssr: false 标志处理所有文件，而具有 Node 环境的测试将使用 ssr: true 处理所有模块。

testTransformMode.ssr

• 类型: string[]
• 默认值: []

对指定测试中的所有模块使用 SSR 转换管道。
Vite 插件在处理这些文件时将收到 ssr: true 标志。

testTransformMode.web

• 类型: string[]
• 默认值: []

首先执行正常的转换管道（针对浏览器环境），然后执行 SSR 重写以在 Node 中运行代码。
Vite 插件在处理这些文件时将收到 ssr: false 标志。

snapshotFormat*

• 类型: PrettyFormatOptions

用于快照测试的格式选项。这些选项将传递给 pretty-format。

TIP

注意：此对象中的 plugins 字段将被忽略。

如果您需要通过 pretty-format 插件扩展快照序列化器，请使用 expect.addSnapshotSerializer API 或 snapshotSerializers 选项。

snapshotSerializers*

• 类型: string[]
• 默认值: []

用于快照测试的快照序列化器模块路径列表。如果您想添加自定义快照序列化器，这将非常有用。有关更多信息，请参见 自定义序列化器。

resolveSnapshotPath*

• 类型: (testPath: string, snapExtension: string) => string
• 默认值: 默认将快照文件存储在 __snapshots__ 目录中

覆盖默认的快照路径。例如，要将快照存储在测试文件旁边：

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    resolveSnapshotPath: (testPath, snapExtension) => testPath + snapExtension,
  },
});

allowOnly

• 类型: boolean
• 默认值: !process.env.CI
• CLI: --allowOnly, --allowOnly=false

允许运行标记为 only 的测试和测试套件。

dangerouslyIgnoreUnhandledErrors*

• 类型: boolean
• 默认值: false
• CLI: --dangerouslyIgnoreUnhandledErrors --dangerouslyIgnoreUnhandledErrors=false

忽略发生的任何未处理的错误。

passWithNoTests*

• 类型: boolean
• 默认值: false
• CLI: --passWithNoTests, --passWithNoTests=false

如果没有找到任何测试，Vitest 将不会报错。

logHeapUsage

• 类型: boolean
• 默认值: false
• CLI: --logHeapUsage, --logHeapUsage=false

在每次测试后显示堆使用情况。有助于调试内存泄漏问题。

css

• 类型: boolean | { include?, exclude?, modules? }

配置是否处理 CSS。排除时，CSS 文件将被替换为空字符串以绕过后续处理。CSS Modules 将返回一个代理，以免影响运行时。

css.include

• 类型: RegExp | RegExp[]
• 默认值: []

应该返回实际 CSS 且由 Vite 管道处理的文件的 RegExp 模式。

TIP

要处理所有 CSS 文件，请使用 /.+/。

css.exclude

• 类型: RegExp | RegExp[]
• 默认值: []

将返回空 CSS 文件的 RegExp 模式。

css.modules

• 类型: { classNameStrategy? }
• 默认值: {}

css.modules.classNameStrategy

• 类型: 'stable' | 'scoped' | 'non-scoped'
• 默认值: 'stable'

如果您决定处理 CSS 文件，则可以配置 CSS 模块中的类名是否需要作用域化。您可以选择以下选项之一：

• stable: 类名将生成为 _${name}_${hashedFilename}，这意味着如果 CSS 内容发生更改，则生成的类将保持不变，但如果文件名被修改或文件被移动到另一个文件夹，则会发生更改。如果您使用快照功能，此设置非常有用。
• scoped: 类名将照常生成，并遵循 css.modules.generateScopedName 方法（如果已配置）且 CSS 处理已启用。默认情况下，文件名将生成为 _${name}_${hash}，其中 hash 包括文件名和文件内容。
• non-scoped: 类名将不会被哈希。

WARNING

默认情况下，Vitest 导出一个代理，绕过 CSS Modules 处理。如果您依赖于类上的 CSS 属性，则必须使用 include 选项启用 CSS 处理。

maxConcurrency

• 类型: number
• 默认值: 5
• CLI: --max-concurrency=10, --maxConcurrency=10

允许同时运行的并发测试数量（标记为 test.concurrent）。

超过此限制的测试将进入队列，等待可用资源。

cache*

• 类型: false
• CLI: --no-cache, --cache=false

使用此选项禁用缓存功能。Vitest 会缓存测试结果，以便优先运行耗时较长和失败的测试。

缓存目录由 Vite 的 cacheDir 选项控制：

import { defineConfig } from 'vitest/config';

export default defineConfig({
  cacheDir: 'custom-folder/.vitest',
});

您可以使用 process.env.VITEST 将目录限制仅用于 Vitest：

import { defineConfig } from 'vitest/config';

export default defineConfig({
  cacheDir: process.env.VITEST ? 'custom-folder/.vitest' : undefined,
});

sequence

• 类型: { sequencer?, shuffle?, seed?, hooks?, setupFiles? }

用于指定测试排序方式的选项。

您可以使用点符号将 sequence 选项传递给 CLI：

npx vitest --sequence.shuffle --sequence.seed=1000

sequence.sequencer*

• 类型: TestSequencerConstructor
• 默认值: BaseSequencer

自定义类，用于定义分片和排序方法。如果您只需要重新定义 sort 和 shard 方法中的一个，可以继承 vitest/node 中的 BaseSequencer，但两者都应该存在。

分片操作会在排序之前执行，并且仅在提供了 --shard 选项时才会生效。

sequence.shuffle

• 类型: boolean | { files?, tests? }
• 默认值: false
• CLI: --sequence.shuffle, --sequence.shuffle=false

如果您希望随机运行文件和测试，可以使用此选项或 CLI 参数 --sequence.shuffle 启用。

Vitest 通常使用缓存来对测试进行排序，以便长时间运行的测试优先执行，从而加快整体测试速度。如果您的文件和测试以随机顺序运行，您将失去这种性能提升，但它可能有助于追踪意外依赖于先前运行的测试。

sequence.shuffle.files

• 类型: boolean
• 默认值: false
• CLI: --sequence.shuffle.files, --sequence.shuffle.files=false

是否随机化文件顺序。注意：启用此选项后，长时间运行的测试将不会优先执行。

sequence.shuffle.tests

• 类型: boolean
• 默认值: false
• CLI: --sequence.shuffle.tests, --sequence.shuffle.tests=false

是否随机化测试用例顺序。

sequence.concurrent

• 类型: boolean
• 默认值: false
• CLI: --sequence.concurrent, --sequence.concurrent=false

如果您希望并行运行测试，可以使用此选项或 CLI 参数 --sequence.concurrent 启用。

sequence.seed*

• 类型: number
• 默认值: Date.now()
• CLI: --sequence.seed=1000

设置随机种子，用于测试以随机顺序运行时。

sequence.hooks

• 类型: 'stack' | 'list' | 'parallel'
• 默认值: 'parallel'
• CLI: --sequence.hooks=<value>

更改钩子函数的执行顺序。

• stack 将以相反的顺序排列 "after" 钩子，"before" 钩子将按照它们定义的顺序运行。
• list 将按照它们定义的顺序排列所有钩子。
• parallel 将并行运行单个组中的钩子（父套件中的钩子仍将在当前套件的钩子之前运行）。

TIP

此选项不影响 onTestFinished。它始终以相反的顺序调用。

sequence.setupFiles

• 类型: 'list' | 'parallel'
• 默认值: 'parallel'
• CLI: --sequence.setupFiles=<value>

更改 setup 文件的执行顺序。

• list 将按照它们定义的顺序运行 setup 文件。
• parallel 将并行运行 setup 文件。

typecheck

用于配置 类型检查 测试环境的选项。

typecheck.enabled

• 类型: boolean
• 默认值: false
• CLI: --typecheck, --typecheck.enabled

在运行常规测试时，同时进行类型检查。

typecheck.only

• 类型: boolean
• 默认值: false
• CLI: --typecheck.only

启用类型检查后，仅运行类型检查测试。使用 CLI 时，此选项将自动启用类型检查。

typecheck.checker

• 类型: 'tsc' | 'vue-tsc' | string
• 默认值: tsc

用于类型检查的工具。Vitest 将根据类型，生成一个带有特定参数的进程，以便于解析。Checker 需要实现与 tsc 相同的输出格式。

您需要安装相应的包才能使用 typechecker：

• tsc 需要 typescript 包
• vue-tsc 需要 vue-tsc 包

您还可以传递自定义二进制文件或命令名称的路径，该路径生成与 tsc --noEmit --pretty false 相同的输出。

typecheck.include

• 类型: string[]
• 默认值: ['**/*.{test,spec}-d.?(c|m)[jt]s?(x)']

匹配测试文件的 Glob 模式。

typecheck.exclude

• 类型: string[]
• 默认值: ['**/node_modules/**', '**/dist/**', '**/cypress/**', '**/.{idea,git,cache,output,temp}/**']

不应被视为测试文件的 Glob 模式。

typecheck.allowJs

• 类型: boolean
• 默认值: false

检查具有 @ts-check 注释的 JS 文件。如果您在 tsconfig 中启用了此选项，则此处的设置不会覆盖 tsconfig 中的设置。

typecheck.ignoreSourceErrors

• 类型: boolean
• 默认值: false

如果 Vitest 在测试文件之外发现错误，则不会导致测试失败。这将完全忽略非测试文件中的错误。

typecheck.tsconfig

• 类型: string
• 默认值: 尝试查找最近的 tsconfig.json

自定义 tsconfig 文件的路径，相对于项目根目录。

slowTestThreshold*

• 类型: number
• 默认值: 300
• CLI: --slow-test-threshold=<number>, --slowTestThreshold=<number>

测试或套件被视为慢速并在结果中报告的阈值毫秒数。

chaiConfig

• 类型: { includeStack?, showDiff?, truncateThreshold? }
• 默认值: { includeStack: false, showDiff: true, truncateThreshold: 40 }

等效于 Chai config。

chaiConfig.includeStack

• 类型: boolean
• 默认值: false

控制是否在断言错误中包含堆栈跟踪。默认值为 false 会抑制错误消息中的堆栈跟踪。

chaiConfig.showDiff

• 类型: boolean
• 默认值: true

影响是否应在抛出的 AssertionError 中包含 showDiff 标志。false 将始终为 false；当断言请求显示差异时，true 才为 true。

chaiConfig.truncateThreshold

• 类型: number
• 默认值: 40

设置断言错误中实际值和期望值的长度阈值。如果超过此阈值，例如对于大型数据结构，该值将替换为类似 [ Array(3) ] 或 { Object (prop1, prop2) } 的内容。设为 0 可完全禁用截断。

此配置选项会影响 test.each 标题和断言错误消息中的截断值。

bail

• 类型: number
• 默认值: 0
• CLI: --bail=<value>

当给定数量的测试失败时停止测试执行。

对于 CI 构建，您可能只关注 100% 成功的构建，并希望在发生测试失败时尽快停止测试执行，因此默认行为可能不适用。bail 选项可用于通过防止 CI 在发生故障时运行更多测试来加速 CI 运行。

retry

• 类型: number
• 默认值: 0
• CLI: --retry=<value>

如果测试失败，则重试指定的次数。

onConsoleLog*

• 类型: (log: string, type: 'stdout' | 'stderr') => boolean | void

测试中 console.log 的自定义处理程序。如果您返回 false，Vitest 将不会将日志打印到控制台。

可用于过滤第三方库的日志。

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    onConsoleLog(log: string, type: 'stdout' | 'stderr'): boolean | void {
      return !(log === 'message from third party library' && type === 'stdout');
    },
  },
});

onStackTrace*

• 类型: (error: Error, frame: ParsedStack) => boolean | void

处理错误时，对堆栈跟踪的每一帧应用过滤函数。第一个参数 error 是一个对象，拥有与标准 Error 相同的属性，但它并非 Error 的实例。

可用于过滤掉来自第三方库的堆栈跟踪帧。

import type { ParsedStack } from 'vitest';
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    onStackTrace(error: Error, { file }: ParsedStack): boolean | void {
      // 如果我们遇到了 ReferenceError，则显示整个堆栈。
      if (error.name === 'ReferenceError') return;

      // 拒绝来自第三方库的所有帧。
      if (file.includes('node_modules')) return false;
    },
  },
});

diff

• 类型: string
• CLI: --diff=<value>

用于生成差异界面的差异配置文件的路径。此选项可用于自定义差异显示。

vitest.diff.ts

import type { DiffOptions } from 'vitest';
import c from 'tinyrainbow';

export default {
  aIndicator: c.bold('--'),
  bIndicator: c.bold('++'),
  omitAnnotationLines: true,
} satisfies DiffOptions;

vitest.config.js

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    diff: './vitest.diff.ts',
  },
});

diff.truncateThreshold

• 类型: number
• 默认值: 0

要显示的差异结果的最大长度。超过此长度的差异内容将被截断。 默认值 0 表示不进行截断。

diff.truncateAnnotation

• 类型: string
• 默认值: '... Diff result is truncated'

如果差异结果被截断，则在差异结果末尾输出的注释。

diff.truncateAnnotationColor

• 类型: DiffOptionsColor = (arg: string) => string
• 默认值: noColor = (string: string): string => string

截断注释的颜色，默认情况下输出没有颜色。

fakeTimers

• 类型: FakeTimerInstallOpts

当使用 vi.useFakeTimers() 时，Vitest 将传递给 @sinon/fake-timers 的选项。

fakeTimers.now

• 类型: number | Date
• 默认值: Date.now()

以指定的 Unix 时间戳初始化模拟计时器。

fakeTimers.toFake

• 类型: ('setTimeout' | 'clearTimeout' | 'setImmediate' | 'clearImmediate' | 'setInterval' | 'clearInterval' | 'Date' | 'nextTick' | 'hrtime' | 'requestAnimationFrame' | 'cancelAnimationFrame' | 'requestIdleCallback' | 'cancelIdleCallback' | 'performance' | 'queueMicrotask')[]
• 默认值: ['setTimeout', 'clearTimeout', 'setImmediate', 'clearImmediate', 'setInterval', 'clearInterval', 'Date']

需要模拟的全局方法和 API 名称数组。

要仅模拟 setTimeout() 和 nextTick()，请将此属性指定为 ['setTimeout', 'nextTick']。

当使用 --pool=forks 在 node:child_process 中运行 Vitest 时，不支持模拟 nextTick。NodeJS 在 node:child_process 内部使用 process.nextTick，并在模拟时挂起。当使用 --pool=threads 运行 Vitest 时，支持模拟 nextTick。

fakeTimers.loopLimit

• 类型: number
• 默认值: 10_000

调用 vi.runAllTimers() 时将运行的最大计时器数。

fakeTimers.shouldAdvanceTime

• 类型: boolean
• 默认值: false

告知 @sinonjs/fake-timers 根据实际系统时间的变化自动增加模拟时间（例如，实际系统时间每变化 20 毫秒，模拟时间也会增加 20 毫秒）。

fakeTimers.advanceTimeDelta

• 类型: number
• 默认值: 20

仅在使用 shouldAdvanceTime: true 时相关。每当实际系统时间变化 advanceTimeDelta 毫秒时，模拟时间递增 advanceTimeDelta 毫秒。

fakeTimers.shouldClearNativeTimers

• 类型: boolean
• 默认: true

告诉 fake timers 通过委托给它们各自的处理程序来清除“原生”（即非 fake）定时器。禁用时，如果定时器在 fake timers 会话开始前存在，可能会导致潜在的意外行为。

workspace*

• 类型: string
• CLI: --workspace=./file.js
• 默认值: 靠近配置文件或根目录的 vitest.{workspace,projects}.{js,ts,json}

相对于 root 的 workspace 配置文件的路径。

isolate

• 类型: boolean
• 默认值: true
• CLI: --no-isolate, --isolate=false

在隔离环境中运行测试。此选项对 vmThreads 和 vmForks 池没有影响。

如果您的代码不依赖副作用（对于 node 环境的项目通常如此），禁用此选项可能会 提高性能。

TIP

您可以使用 poolOptions 属性为特定池禁用隔离。

includeTaskLocation

• 类型: boolean
• 默认值: false

当 Vitest API 在 reporters 中接收任务时，是否应包含 location 属性。如果您有很多测试，这可能会导致轻微的性能下降。

location 属性具有与原始文件中 test 或 describe 位置相对应的 column 和 line 值。

如果您没有明确禁用此选项，并且您正在通过以下方式运行 Vitest，则此选项将自动启用：

• Vitest UI
• 或者使用 浏览器模式 而不是 headless 模式
• 或者使用 HTML 报告器

TIP

如果您不使用依赖于此的自定义代码，则此选项无效。

snapshotEnvironment

• 类型: string

自定义快照环境实现文件的路径。如果您在不支持 Node.js API 的环境中运行测试，这将非常有用。此选项对浏览器运行器没有任何影响。

该对象需要实现 SnapshotEnvironment 接口，并用于解析和读写快照文件：

export interface SnapshotEnvironment {
  getVersion: () => string;
  getHeader: () => string;
  resolvePath: (filepath: string) => Promise<string>;
  resolveRawPath: (testPath: string, rawPath: string) => Promise<string>;
  saveSnapshotFile: (filepath: string, snapshot: string) => Promise<void>;
  readSnapshotFile: (filepath: string) => Promise<string | null>;
  removeSnapshotFile: (filepath: string) => Promise<void>;
}

若只需覆盖部分 API，您可以从 vitest/snapshot 入口点扩展默认的 VitestSnapshotEnvironment。

WARNING

此为底层选项，仅建议在无法使用默认 Node.js API 的高级场景中使用。

如果您只需要配置快照功能，请使用 snapshotFormat 或 resolveSnapshotPath 选项。

env

• 类型： Partial<NodeJS.ProcessEnv>

测试期间可在 process.env 和 import.meta.env 中使用的环境变量。这些变量在主进程中不可用（例如在 globalSetup 中）。

expect

• 类型： ExpectOptions

expect.requireAssertions

• 类型： boolean
• 默认值： false

与在每个测试开始时调用 expect.hasAssertions() 相同。这确保不会有测试意外通过。

TIP

这仅适用于 Vitest 的 expect。如果您使用 assert 或 .should 断言，它们将不会计入，并且您的测试将因缺少 expect 断言而失败。

您可以通过调用 vi.setConfig({ expect: { requireAssertions: false } }) 来更改此值。此配置将应用于之后的所有 expect 调用，直到手动调用 vi.resetConfig。

expect.poll

expect.poll 的全局配置选项。这些选项与您传递给 expect.poll(condition, options) 的选项相同。

expect.poll.interval

• 类型： number
• 默认值： 50

以毫秒为单位的轮询间隔

expect.poll.timeout

• 类型： number
• 默认值： 1000

以毫秒为单位的轮询超时时间

printConsoleTrace

• 类型： boolean
• 默认值： false

调用任何 console方法时始终打印控制台跟踪。这对于调试非常有用。