vitest-dev · NoiseFan · Apr 7, 2026 · Mar 19, 2026 · Mar 19, 2026 · Mar 19, 2026
diff --git a/.vitepress/config.ts b/.vitepress/config.ts
@@ -262,11 +262,11 @@ export default ({ mode }: { mode: string }) => {
       sidebar: {
         '/config': [
           {
-            text: 'Config Reference',
+            text: '配置索引',
             collapsed: false,
             items: [
               {
-                text: '配置文件',
+                text: '配置 Vitest',
                 link: '/config/',
               },
               {

diff --git a/api/expect.md b/api/expect.md
@@ -861,9 +861,9 @@ test('throws non-Error values', () => {
 })
 ```
 :::
-<!-- TODO: translation -->
-:::warning Unhandled Rejections with Fake Timers
-When using fake timers, an async function that rejects _during_ a `vi.advanceTimersByTimeAsync` call will trigger an [unhandled rejection](https://nodejs.org/api/process.html#event-unhandledrejection) — even if you later assert it with `.rejects.toThrow()`. This happens because the error is thrown before the `expect` chain has a chance to catch it.
+
+:::warning 使用假定时器时的未处理拒绝
+当使用假定时器时，在 `vi.advanceTimersByTimeAsync` 调用期间被拒绝的异步函数会触发 [未处理的拒绝](https://nodejs.org/api/process.html#event-unhandledrejection)，即使你稍后使用 `.rejects.toThrow()` 进行断言。这是因为错误在 `expect` 链有机会捕获之前就被抛出了。
 
 ```ts
 async function foo() {
@@ -876,12 +876,12 @@ test('rejects', async () => {
 
   await vi.advanceTimersByTimeAsync(100)
 
-  // The assertion passes, but the error was already "unhandled" during advanceTimersByTimeAsync
+  // 断言虽然通过，但在 advanceTimersByTimeAsync 期间错误已经是 “未处理” 状态
   await expect(result).rejects.toThrow()
 })
 ```
 
-To avoid this, prefer [`vi.setTimerTickMode('nextTimerAsync')`](/api/vi#vi-settimertickmode) so that timers tick automatically as promises settle, without needing a manual advance:
+为避免这种情况，推荐使用 [`vi.setTimerTickMode('nextTimerAsync')`](/api/vi#vi-settimertickmode)，这样定时器会在 Promise 解决时自动触发，无需手动调用：
 
 ```ts
 beforeEach(() => {
@@ -890,12 +890,12 @@ beforeEach(() => {
 })
 
 test('rejects', async () => {
-  // No advanceTimersByTimeAsync needed — the error is caught by rejects.toThrow()
+  // 不需要 advanceTimersByTimeAsync，错误会被 rejects.toThrow() 捕获
   await expect(foo()).rejects.toThrow('boom')
 })
 ```
 
-Alternatively, set up the `.rejects.toThrow()` assertion _before_ advancing timers so the rejection is handled immediately:
+或者，也可以在推进计时器 _之前_ 设置 `.rejects.toThrow()` 断言，这样就能立即处理失败情况：
 
 ```ts
 test('rejects', async () => {
@@ -1606,10 +1606,10 @@ test('spy nth called with', () => {
 ```
 
 ## returned <Version>4.1.0</Version> {#returned}
-<!-- TODO: translation -->
-- **Type:** `(value: any) => void`
 
-Chai-style assertion that checks if a spy returned a specific value at least once. This is equivalent to `toHaveReturnedWith(value)`.
+- **类型:**`(value: any) => void`
+
+Chai 风格断言，用于检查 spy 函数是否至少返回过一次指定的值。等价于 `toHaveReturnedWith(value)`。
 
 ```ts
 import { expect, test, vi } from 'vitest'

diff --git a/api/mock.md b/api/mock.md
@@ -20,8 +20,8 @@ getApplesSpy.mock.calls.length === 1
 
 要验证 mock 的行为，请通过 [`expect`](/api/expect) 调用类似 [`toHaveBeenCalled`](/api/expect#tohavebeencalled) 的断言方法；以下 API 参考汇总了所有可用来操控 mock 的属性和方法。
 
-::: warning IMPORTANT
-Vitest spies inherit implementation's [`length`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/length) property when initialized, but it doesn't override it if the implementation was changed later:
+::: warning 重要说明
+Vitest 的 spy 函数在初始化时会继承被监听函数的 [`length`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/length) 属性，但后续如果修改被监听函数，则不会覆盖该属性值。
 
 ::: code-group
 ```ts [vi.fn]
@@ -50,10 +50,8 @@ fn.length // == 2
 以下类型中的自定义函数实现使用泛型 `<T>` 进行标记。
 :::
 
-<!-- TODO: translation -->
-
-::: warning Class Support {#class-support}
-Shorthand methods like `mockReturnValue`, `mockReturnValueOnce`, `mockResolvedValue` and others cannot be used on a mocked class. Class constructors have [unintuitive behaviour](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/constructor) regarding the return value:
+::: warning 类支持 {#class-support}
+像 `mockReturnValue`、`mockReturnValueOnce`、`mockResolvedValue` 这样的简写方法不能用于模拟类。类构造函数在返回值方面具有[反直觉的行为](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/constructor)：
 
 ```ts {2,7}
 const CorrectDogClass = vi.fn(class {
@@ -73,16 +71,16 @@ Marti instanceof CorrectDogClass // ✅ true
 Newt instanceof IncorrectDogClass // ❌ false!
 ```
 
-Even though the shapes are the same, the _return value_ from the constructor is assigned to `Newt`, which is a plain object, not an instance of a mock. Vitest guards you against this behaviour in shorthand methods (but not in `mockImplementation`!) and throws an error instead.
+尽管接口规范相同，但构造函数的 _返回值_ 被赋给了 `Newt`，这是一个普通对象，而非模拟类的实例。Vitest 会在简写方法中（但不会在 `mockImplementation` 中！）防止这种行为，转而抛出错误。
 
-If you need to mock constructed instance of a class, consider using the `class` syntax with `mockImplementation` instead:
+如果需要模拟类的构造实例，考虑改用 `class` 语法配合 `mockImplementation`：
 
 ```ts
 mock.mockReturnValue({ hello: () => 'world' }) // [!code --]
 mock.mockImplementation(class { hello = () => 'world' }) // [!code ++]
 ```
 
-If you need to test the behaviour where this is a valid use case, you can use `mockImplementation` with a `constructor`:
+如果需要测试这种有效用例的行为，可以使用带有 `constructor` 的 `mockImplementation`：
 
 ```ts
 mock.mockImplementation(class {
@@ -425,19 +423,18 @@ const myMockFn = vi
 // 'first call', 'second call', 'default', 'default'
 console.log(myMockFn(), myMockFn(), myMockFn(), myMockFn())
 ```
-<!-- TODO: translation -->
 ## mockThrow <Version>4.1.0</Version> {#mockthrow}
 
 ```ts
 function mockThrow(value: unknown): Mock<T>
 ```
 
-Accepts a value that will be thrown whenever the mock function is called.
+接收一个值，该值会在每次调用模拟函数时被抛出。
 
 ```ts
 const myMockFn = vi.fn()
 myMockFn.mockThrow(new Error('error message'))
-myMockFn() // throws Error<'error message'>
+myMockFn() // 抛出 <'error message'> 错误
 ```
 
 ## mockThrowOnce <Version>4.1.0</Version> {#mockthrowonce}
@@ -446,7 +443,7 @@ myMockFn() // throws Error<'error message'>
 function mockThrowOnce(value: unknown): Mock<T>
 ```
 
-Accepts a value that will be thrown during the next function call. If chained, every consecutive call will throw the specified value.
+接收一个值，该值会在下一次函数调用时被抛出。如果链式调用，每次连续调用都会抛出指定的值。
 
 ```ts
 const myMockFn = vi
@@ -476,8 +473,8 @@ fn('arg3')
 
 fn.mock.calls
 === [
-  ['arg1', 'arg2'], // first call
-  ['arg3'], // second call
+  ['arg1', 'arg2'], // 首次调用
+  ['arg3'], // 第二次调用
 ]
 ```
 

diff --git a/api/vi.md b/api/vi.md
@@ -1071,7 +1071,7 @@ function useFakeTimers(config?: FakeTimerInstallOpts): Vitest
 
 ### vi.setTimerTickMode <Version>4.1.0</Version> {#vi-settimertickmode}
 
-- **Type:** `(mode: 'manual' | 'nextTimerAsync') => Vitest | (mode: 'interval', interval?: number) => Vitest`
+- **类型:**`(mode: 'manual' | 'nextTimerAsync') => Vitest | (mode: 'interval', interval?: number) => Vitest`
 
 Controls how fake timers are advanced.
 
@@ -1125,9 +1125,9 @@ function useRealTimers(): Vitest
 
 当定时器用完后，我们可以调用此方法将模拟的计时器返回到其原始实现。之前调度的计时器都将被丢弃。
 
-## 辅助函数{#miscellaneous}
+## 工具函数{#miscellaneous}
 
-Vitest 提供的一组有用的辅助函数。
+Vitest 提供的一组有用的工具函数。
 
 ### vi.waitFor {#vi-waitfor}
 
@@ -1342,17 +1342,15 @@ function resetConfig(): void
 
 如果之前调用过 [`vi.setConfig`](#vi-setconfig) ，则会将配置重置为原始状态。
 
-<!-- TODO: translation -->
-
 ### vi.defineHelper <Version>4.1.0</Version> {#vi-defineHelper}
 
 ```ts
 function defineHelper<F extends (...args: any) => any>(fn: F): F
 ```
 
-Wraps a function to create an assertion helper. When an assertion fails inside the helper, the error stack trace will point to where the helper was called, not inside the helper itself. This makes it easier to identify the source of test failures when using custom assertion functions.
+封装函数以创建断言工具函数。当功能函数内断言失败时，错误堆栈会指向调用工具函数的位置，而非工具函数内部。这使得使用自定义断言函数时能更轻松定位测试失败根源。
 
-Works with both synchronous and asynchronous functions, and supports `expect.soft()`.
+同时支持同步和异步函数，并兼容 `expect.soft()` 用法。
 
 ```ts
 import { expect, vi } from 'vitest'
@@ -1362,11 +1360,11 @@ const assertPair = vi.defineHelper((a, b) => {
 })
 
 test('example', () => {
-  assertPair('left', 'right') // Error points to this line
+  assertPair('left', 'right') // 错误将指向此行
 })
 ```
 
-Example output:
+示例输出：
 
 <!-- eslint-skip -->
 ```js

diff --git a/config/alias.md b/config/alias.md
@@ -1,18 +1,18 @@
 ---
-title: alias | Config
+title: alias | 配置
 outline: deep
 ---
 
 # alias
 
-- **Type:** `Record<string, string> | Array<{ find: string | RegExp, replacement: string, customResolver?: ResolverFunction | ResolverObject }>`
+- **类型:** `Record<string, string> | Array<{ find: string | RegExp, replacement: string, customResolver?: ResolverFunction | ResolverObject }>`
 
-Define custom aliases when running inside tests. They will be merged with aliases from `resolve.alias`.
+在测试环境中定义自定义别名。这些别名将与 `resolve.alias` 中的配置合并使用。
 
 ::: warning
-Vitest uses Vite SSR primitives to run tests which has [certain pitfalls](https://vitejs.dev/guide/ssr.html#ssr-externals).
+Vitest 基于 Vite 的 SSR 底层机制运行测试，可能存在 [潜在的缺陷](https://cn.vitejs.dev/guide/ssr.html#ssr-externals)。
 
-1. Aliases affect only modules imported directly with an `import` keyword by an [inlined](/config/server#server-deps-inline) module (all source code is inlined by default).
-2. Vitest does not support aliasing `require` calls.
-3. If you are aliasing an external dependency (e.g., `react` -> `preact`), you may want to alias the actual `node_modules` packages instead to make it work for externalized dependencies. Both [Yarn](https://classic.yarnpkg.com/en/docs/cli/add/#toc-yarn-add-alias) and [pnpm](https://pnpm.io/aliases/) support aliasing via the `npm:` prefix.
+1. 别名仅影响由 [内联模块](/config/server#server-deps-inline) 通过 `import` 关键字直接导入的模块 （默认情况下所有源代码均被内联）。
+2. Vitest 不支持对 `require` 调用进行别名配置。
+3. 如果我们要为外部依赖项设置别名（例如，`react` -> `preact`），建议直接对 `node_modules` 中的实际包进行别名配置，以确保该方案在外部化依赖场景下同样生效。[Yarn](https://classic.yarnpkg.com/en/docs/cli/add/#toc-yarn-add-alias) 和 [pnpm](https://pnpm.io/aliases/) 均支持通过 `npm:` 前缀实现别名功能。
 :::
diff --git a/config/allowonly.md b/config/allowonly.md
@@ -1,23 +1,21 @@
 ---
-title: allowOnly | Config
+title: allowOnly | 配置
 outline: deep
 ---
 
-<!-- TODO: translation -->
-
 # allowOnly
 
-- **Type**: `boolean`
-- **Default**: `!process.env.CI`
-- **CLI:** `--allowOnly`, `--allowOnly=false`
+- **类型:**: `boolean`
+- **默认值:**: `!process.env.CI`
+- **命令行终端:** `--allowOnly`, `--allowOnly=false`
 
-By default, Vitest does not permit tests marked with the [`only`](/api/test#test-only) flag in Continuous Integration (CI) environments. Conversely, in local development environments, Vitest allows these tests to run.
+默认情况下，Vitest 不允许在持续集成（CI）环境中运行带有 [`only`](/api/test#test-only) 标记的测试。相反，在本地开发环境中，Vitest 允许运行这些测试。
 
 ::: info
-Vitest uses [`std-env`](https://npmx.dev/package/std-env) package to detect the environment.
+Vitest 使用 [`std-env`](https://npmx.dev/package/std-env) 包来检测环境。
 :::
 
-You can customize this behavior by explicitly setting the `allowOnly` option to either `true` or `false`.
+你可以通过显式设置 `allowOnly` 选项为 `true` 或 `false` 来自定义此行为。
 
 ::: code-group
 ```js [vitest.config.js]
@@ -34,6 +32,6 @@ vitest --allowOnly
 ```
 :::
 
-When enabled, Vitest will not fail the test suite if tests marked with [`only`](/api/test#test-only) are detected, including in CI environments.
+启用时，即使检测到带有 [`only`](/api/test#test-only) 标记的测试，Vitest 也不会导致测试套件失败，包括在 CI 环境中。
 
-When disabled, Vitest will fail the test suite if tests marked with [`only`](/api/test#test-only) are detected, including in local development environments.
+禁用时时，如果检测到带有 [`only`](/api/test#test-only) 标记的测试，Vitest 将导致测试套件失败，包括在本地开发环境中。
diff --git a/config/api.md b/config/api.md
@@ -1,34 +1,32 @@
 ---
-title: api | Config
+title: api | 配置
 outline: deep
 ---
 
-<!-- TODO: translation -->
-
 # api
 
-- **Type:** `boolean | number | object`
-- **Default:** `false`
-- **CLI:** `--api`, `--api.port`, `--api.host`, `--api.strictPort`
+- **类型:** `boolean | number | object`
+- **默认值:** `false`
+- **命令行终端:** `--api`, `--api.port`, `--api.host`, `--api.strictPort`
 
-Listen to port and serve API for [the UI](/guide/ui) or [browser server](/guide/browser/). When set to `true`, the default port is `51204`.
+监听端口并提供 API 服务，用于 [UI 模式](/guide/ui) 或 [浏览器服务](/guide/browser/)。设为 `true` 时，默认端口为 `51204`。
 
 ## api.allowWrite <Version>4.1.0</Version> {#api-allowwrite}
 
-- **Type:** `boolean`
-- **Default:** `true` if not exposed to the network, `false` otherwise
+- **类型:** `boolean`
+- **默认值:** `true` 表示未暴露在公共网络中，`false` 则表示已暴露
 
-Vitest server can save test files or snapshot files via the API. This allows anyone who can connect to the API the ability to run any arbitrary code on your machine.
+Vitest 服务器可以通过 API 保存测试文件或快照文件。这意味着任何能连接到 API 的人都可以在你的机器上运行任意代码。
 
-::: danger SECURITY ADVICE
-Vitest does not expose the API to the internet by default and only listens on `localhost`. However if `host` is manually exposed to the network, anyone who connects to it can run arbitrary code on your machine, unless `api.allowWrite` and `api.allowExec` are set to `false`.
+::: danger 安全警告
+Vitest 默认不会将 API 暴露到互联网，仅在 `localhost` 上监听。但如果 `host` 被手动暴露到网络，任何连接到它的人都可以在你的机器上运行任意代码，除非将 `api.allowWrite` 和 `api.allowExec` 设置为`false`。
 
-If the host is set to anything other than `localhost` or `127.0.0.1`, Vitest will set `api.allowWrite` and `api.allowExec` to `false` by default. This means that any write operations (like changing the code in the UI) will not work. However, if you understand the security implications, you can override them.
+如果 host 设置为 `localhost` 或 `127.0.0.1` 以外的任何值，Vitest 会默认将 `api.allowWrite` 和 `api.allowExec` 设置为 `false`。这意味着任何写入操作（例如 在 UI 模式中修改代码）将不起作用。如果你了解安全风险，可以覆盖这些设置。
 :::
 
 ## api.allowExec <Version>4.1.0</Version> {#api-allowexec}
 
-- **Type:** `boolean`
-- **Default:** `true` if not exposed to the network, `false` otherwise
+- **类型:** `boolean`
+- **默认值:** `true` 表示未暴露在公共网络中，`false` 则表示已暴露
 
-Allows running any test file via the API. See the security advice in [`api.allowWrite`](#api-allowwrite).
+允许通过 API 运行任何测试文件。详细安全建议请参阅 [`api.allowWrite`](#api-allowwrite)。
diff --git a/config/attachmentsdir.md b/config/attachmentsdir.md
@@ -1,11 +1,11 @@
 ---
-title: attachmentsDir | Config
+title: attachmentsDir | 配置
 outline: deep
 ---
 
 # attachmentsDir
 
-- **Type:** `string`
-- **Default:** `'.vitest-attachments'`
+- **类型:** `string`
+- **默认值:** `'.vitest-attachments'`
 
-Directory path for storing attachments created by [`context.annotate`](/guide/test-context#annotate) relative to the project root.
+用于存储 [`context.annotate`](/guide/test-context#annotate) 所创建附件的目录路径（相对于项目根目录）。
diff --git a/config/bail.md b/config/bail.md
@@ -1,14 +1,14 @@
 ---
-title: bail | Config
+title: bail | 配置
 outline: deep
 ---
 
 # bail
 
-- **Type:** `number`
-- **Default:** `0`
-- **CLI**: `--bail=<value>`
+- **类型:** `number`
+- **默认值:** `0`
+- **命令行终端:** `--bail=<value>`
 
-Stop test execution when given number of tests have failed.
+当指定数量的测试用例失败时立即终止测试执行。
 
-By default Vitest will run all of your test cases even if some of them fail. This may not be desired for CI builds where you are only interested in 100% successful builds and would like to stop test execution as early as possible when test failures occur. The `bail` option can be used to speed up CI runs by preventing it from running more tests when failures have occurred.
+默认情况下，即使部分测试失败，Vitest 仍会继续运行所有测试用例。对于仅关注 100% 成功构建的 CI 环境而言，这种行为可能不符合需求——您可能希望在测试出现失败时尽早终止执行。通过配置 `bail` 选项，可在发生失败时阻止后续测试运行，从而加速 CI 流程。
diff --git a/config/benchmark.md b/config/benchmark.md
@@ -1,5 +1,5 @@
 ---
-title: benchmark | Config
+title: benchmark | 配置
 outline: deep
 ---