# jest-diff 中文文档

规范地址：https://npmcn.com/package/jest-diff/

版本：30\.5\.2
npm 元数据更新时间：2026-09-18T13:56:26.197Z
中文译文更新时间：2026-11-05T15:41:56.303Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/jest-diff
原文对照：https://npmcn.com/package/jest-diff/?lang=original
项目主页：https://github.com/jestjs/jest#readme
源码仓库：https://github.com/jestjs/jest

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：80.8 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：^18\.14\.0 \|\| ^20\.0\.0 \|\| ^22\.0\.0 \|\| \>=24\.0\.0
- 运行依赖：4 个
- 首次发布：2016-07-02T06:32:14.622Z
- 最新版本发布：2026-09-18T13:56:26.012Z
- 近 30 天下载量：305354739（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：255（近 12 个月 6 个）

## 中文简介

清晰显示差异,以便人们可以自信地审查变化.

## 安装

```sh
npm install jest-diff
```

也可以使用：`pnpm add jest-diff`、`yarn add jest-diff`、`bun add jest-diff`

## README

# 欢呼声

清晰显示差异,以便人们可以自信地审查变化.

这个 `diff` 命名导出序列化 JavaScript **数值**,然后返回包含比较线的字符串.

比较两个命名的出口 **字符串** 逐个字符 :

-   `diffStringsUnified` 返回字符串.
-   `diffStringsRaw` 返回数组 `Diff` 对象.

3个出口名称比较 **字符串数组** 按行数 :

-   `diffLinesUnified` 财务报告和审定财务报表 `diffLinesUnified2` 返回字符串.
-   `diffLinesRaw` 返回数组 `Diff` 对象.

## 安装

要添加此软件包作为工程的依赖, 请运行以下任一命令 :

-   `npm install jest-diff`
-   `yarn add jest-diff`

## 使用时间 `diff()`

给定 Java 脚本 **数值**, (中文(简体) ), `diff(a, b, options?)` 执行下列规定:

1.  **序列化** 使用 `pretty-format` 软件包
2.  **比较** 使用 `diff-sequences` 软件包
3.  **格式** 使用 `chalk` 软件包

要使用此函数,请写出以下任一部分:

-   `const {diff} = require('jest-diff');` 在共同JS模块中
-   `import {diff} from 'jest-diff';` 在ECMAScript模块中

### 实例 `diff()`

```js
const a = ['delete', 'common', 'changed from'];
const b = ['common', 'changed to', 'insert'];

const difference = diff(a, b);
```

回来的 **字符串** 包括:

-   注释行: 描述两个带有标签的更改指标, 和一个空白行
-   比较线:类似于GitHub上的“统一”观点,但 `Expected` 线路是绿色的, `Received` 行为红色,常见行为暗色(默认情况下,见选项)

```diff
- Expected
+ Received

  Array [
-   "delete",
    "common",
-   "changed from",
+   "changed to",
+   "insert",
  ]
```

### 边际案件 `diff()`

以下是返回值的边框:

-   `' Comparing two different types of values. …'` 如果争论有 **不同类型** 根据 `jest-get-type` 软件包(不同类别的软件包有相同的 `'object'` 类型)
-   `'Compared values have no visual difference.'` 如果这些论点有 **优惠身份** 根据 `Object.is` 方法或 **相同的序列化** 根据 `pretty-format` 软件包
-   `null` 如果这两个论点都是所谓的 **非对称匹配者** 在茉莉花或欢乐

## 使用 diffStrings 统一

鉴于 **字符串**, (中文(简体) ), `diffStringsUnified(a, b, options?)` 执行下列规定:

1.  **比较** 使用 `diff-sequences` 软件包
2.  **清理** 小(常为偶发)常见的下弦,又名相花
3.  **格式** 使用 `chalk` 软件包

虽然这个功能主要用于 **多线** 字符串,可以比较任意字符串.

写以下任一:

-   `const {diffStringsUnified} = require('jest-diff');` 在共同JS模块中
-   `import {diffStringsUnified} from 'jest-diff';` 在ECMAScript模块中

### DiffStrings 实例

```js
const a = 'common\nchanged from';
const b = 'common\nchanged to';

const difference = diffStringsUnified(a, b);
```

回来的 **字符串** 包括:

-   注释行: 描述两个带有标签的更改指标, 和一个空白行
-   比较线:类似于GitHub上的“统一”观点,以及 **更改子字符串** 有过 **反转** 前景和背景颜色(即, `from` 有白绿相间 `to` 有正对正对正红,以下示例未显示)

```diff
- Expected
+ Received

  common
- changed from
+ changed to
```

### DiffStrings的性能统一

获得好处 **更改子字符串** 在比较行内,逐个字符比较的计算成本(时间和空间)高于逐行比较.

如果输入字符串可以 **任意长度**,我们建议调用代码设定一个限制, 超过这个限制,再分弦,然后调用 `diffLinesUnified` 换句话说 例如,Jest如果任意一个字符串的长度大于20K字符,则会回落到逐行比较.

## 单行道的使用

鉴于 **字符串数组**, (中文(简体) ), `diffLinesUnified(aLines, bLines, options?)` 执行下列规定:

1.  **比较** 使用 `diff-sequences` 软件包
2.  **格式** 使用 `chalk` 软件包

当字符串被分割成行而不需要在行内看到已更改的子字符串时,您可能会调用此函数 .

### 单行线示例

```js
const aLines = ['delete', 'common', 'changed from'];
const bLines = ['common', 'changed to', 'insert'];

const difference = diffLinesUnified(aLines, bLines);
```

```diff
- Expected
+ Received

- delete
  common
- changed from
+ changed to
+ insert
```

### DiffLines的边缘病例 统一或diffStrings

以下是参数和返回值的边缘实例:

-   两者 `a` 财务报告和审定财务报表 `b` 是空字符串:没有比较线
-   仅限 `a` 是空字符串: 所有比较行都有 `bColor` 财务报告和审定财务报表 `bIndicator` (见选项)
-   仅限 `b` 是空字符串: 所有比较行都有 `aColor` 财务报告和审定财务报表 `aIndicator` (见选项)
-   `a` 财务报告和审定财务报表 `b` 等同非空字符串: 所有比较线都有 `commonColor` 财务报告和审定财务报表 `commonIndicator` (见选项)

## DiffLine 统一使用 2

两个 **双对** 数组弦, `diffLinesUnified2(aLinesDisplay, bLinesDisplay, aLinesCompare, bLinesCompare, options?)` 执行下列规定:

1.  **比较** 一对 `Compare` 使用 `diff-sequences` 软件包
2.  **格式** 组合中的对应行 `Display` 使用 `chalk` 软件包

Jest称,如果唯一的区别是缩进,则将此函数视为通行而非更改.

您可以将此函数称为大小写不敏感或Unicode等同的行比较 .

### DiffLine 实例统一2

```js
import {format} from 'pretty-format';

const a = {
  text: 'Ignore indentation in serialized object',
  time: '2019-09-19T12:34:56.000Z',
  type: 'CREATE_ITEM',
};
const b = {
  payload: {
    text: 'Ignore indentation in serialized object',
    time: '2019-09-19T12:34:56.000Z',
  },
  type: 'CREATE_ITEM',
};

const difference = diffLinesUnified2(
  // serialize with indentation to display lines
  format(a).split('\n'),
  format(b).split('\n'),
  // serialize without indentation to compare lines
  format(a, {indent: 0}).split('\n'),
  format(b, {indent: 0}).split('\n'),
);
```

这个 `text` 财务报告和审定财务报表 `time` 属性是常见的,因为他们唯一的区别是缩进:

```diff
- Expected
+ Received

  Object {
+   payload: Object {
      text: 'Ignore indentation in serialized object',
      time: '2019-09-19T12:34:56.000Z',
+   },
    type: 'CREATE_ITEM',
  }
```

前面的例子说明了为什么(至少对于缩进来说)函数返回来自 `bLinesDisplay` 数组而不是从 `aLinesDisplay` 阵列.

## DiffStringsRaw 的使用法

鉴于 **字符串** 和布尔的选项, `diffStringsRaw(a, b, cleanup)` 执行下列规定:

1.  **比较** 使用 `diff-sequences` 软件包
2.  可选择 **清理** 小(常为偶发)常见的下弦,又名相花

因为 `diffStringsRaw` 返回差数为 **数据** 而不是字符串,您可以按应用程序的要求格式化它(例如,在浏览器的HTML标记上加注,而不是在控制台的逃生序列上加注).

回来的 **数组** 将子字符串描述为 `Diff` 类,该类的调用代码可以像数组拖动一样访问:

指数值 `0` 属于下列情况之一:

| 价值 | 命名导出 | 说明 |
| --: | :-- | :-- |
| `0` | `DIFF_EQUAL` | 内 `a` 内 `b` |
| `-1` | `DIFF_DELETE` | 内 `a` 但没有在 `b` |
| `1` | `DIFF_INSERT` | 内 `b` 但没有在 `a` |

指数值 `1` 是一个子串 `a` 或者说 `b` 或两者兼有.

### 有清理的 diffStringsRaw 示例

```js
const diffs = diffStringsRaw('changed from', 'changed to', true);
```

| `i` | `diffs[i][0]` | `diffs[i][1]` |
| --: | :-- | :-- |
| `0` | `0` | `'changed '` |
| `1` | `-1` | `'from'` |
| `2` | `1` | `'to'` |

### 未清理的 diffStringsRaw 示例

```js
const diffs = diffStringsRaw('changed from', 'changed to', false);
```

| `i` | `diffs[i][0]` | `diffs[i][1]` |
| --: | :-- | :-- |
| `0` | `0` | `'changed '` |
| `1` | `-1` | `'fr'` |
| `2` | `1` | `'t'` |
| `3` | `0` | `'o'` |
| `4` | `-1` | `'m'` |

### DiffStringsRaw 高级导入

这是所有你可能需要的商品 `diffStringsRaw` 函数 :

-   `const {DIFF_DELETE, DIFF_EQUAL, DIFF_INSERT, Diff, diffStringsRaw} = require('jest-diff');` 在共同JS模块中
-   `import {DIFF_DELETE, DIFF_EQUAL, DIFF_INSERT, Diff, diffStringsRaw} from 'jest-diff';` 在ECMAScript模块中

写一个 **格式化** 函数,您可能需要命名常数(和 `Diff` 在 TypeScript 说明中.

如果您写入了应用程序 **清理** 算法,那么你可能需要调用 `Diff` 构造器 :

```js
const diffCommon = new Diff(DIFF_EQUAL, 'changed ');
const diffDelete = new Diff(DIFF_DELETE, 'from');
const diffInsert = new Diff(DIFF_INSERT, 'to');
```

## DiffLinesRaw的使用量

鉴于 **字符串数组**, (中文(简体) ), `diffLinesRaw(aLines, bLines)` 执行下列规定:

-   **比较** 使用 `diff-sequences` 软件包

因为 `diffLinesRaw` 返回差数为 **数据** 而不是字符串,您可以根据应用程序的要求格式化它.

### DiffLineRaw 实例

```js
const aLines = ['delete', 'common', 'changed from'];
const bLines = ['common', 'changed to', 'insert'];

const diffs = diffLinesRaw(aLines, bLines);
```

| `i` | `diffs[i][0]` | `diffs[i][1]` |
| --: | :-- | :-- |
| `0` | `-1` | `'delete'` |
| `1` | `0` | `'common'` |
| `2` | `-1` | `'changed from'` |
| `3` | `1` | `'changed to'` |
| `4` | `1` | `'insert'` |

### DiffLinesRaw 边缘案例

如果你打电话 `string.split('\n')` 用于空字符串 :

-   结果 `['']` 包含空字符串的数组
-   改为 `[]` 空数组

根据申请,你可能会打电话 `diffLinesRaw` 使用任意一个阵列.

### 拆分方法示例

```js
import {diffLinesRaw} from 'jest-diff';

const a = 'non-empty string';
const b = '';

const diffs = diffLinesRaw(a.split('\n'), b.split('\n'));
```

| `i` | `diffs[i][0]` | `diffs[i][1]` |
| --: | :-- | :-- |
| `0` | `-1` | `'non-empty string'` |
| `1` | `1` | `''` |

您可以格式化如下:

```diff
- Expected  - 1
+ Received  + 1

- non-empty string
+
```

### 拆分Lines0 函数示例

对于边缘案件的行为,如 `diffLinesUnified` 函数,您可以定义 `splitLines0` 函数,该函数给出了空字符串,返回 `[]` 空数组 :

```js
export const splitLines0 = string =>
  string.length === 0 ? [] : string.split('\n');
```

```js
import {diffLinesRaw} from 'jest-diff';

const a = '';
const b = 'line 1\nline 2\nline 3';

const diffs = diffLinesRaw(a.split('\n'), b.split('\n'));
```

| `i` | `diffs[i][0]` | `diffs[i][1]` |
| --: | :-- | :-- |
| `0` | `1` | `'line 1'` |
| `1` | `1` | `'line 2'` |
| `2` | `1` | `'line 3'` |

您可以格式化如下:

```diff
- Expected  - 0
+ Received  + 3

+ line 1
+ line 2
+ line 3
```

相对于 `diffLinesRaw` 函数 `diffLinesUnified` 财务报告和审定财务报表 `diffLinesUnified2` 函数 **自动** 转换由字符串计算的数组参数 `split` 方法,所以呼叫者这样做 **没有** 需要一个 `splitLine0` 函数.

## 选项

默认选项是当断言失败时的报表 `expect` jest 使用的软件包.

对于其他应用程序,您可以提供一个选项对象作为第三个参数:

-   `diff(a, b, options)`
-   `diffStringsUnified(a, b, options)`
-   `diffLinesUnified(aLines, bLines, options)`
-   `diffLinesUnified2(aLinesDisplay, bLinesDisplay, aLinesCompare, bLinesCompare, options)`

### 选项对象的属性

| 名称 | 默认 |
| --: | :-- |
| `aAnnotation` | `'Expected'` |
| `aColor` | `chalk.green` |
| `aIndicator` | `'-'` |
| `bAnnotation` | `'Received'` |
| `bColor` | `chalk.red` |
| `bIndicator` | `'+'` |
| `changeColor` | `chalk.inverse` |
| `changeLineTrailingSpaceColor` | `string => string` |
| `commonColor` | `chalk.dim` |
| `commonIndicator` | `' '` |
| `commonLineTrailingSpaceColor` | `string => string` |
| `compareKeys` | `undefined` |
| `contextLines` | `5` |
| `emptyFirstOrLastLinePlaceholder` | `''` |
| `expand` | `true` |
| `includeChangeCounts` | `false` |
| `omitAnnotationLines` | `false` |
| `patchColor` | `chalk.yellow` |

关于这些选项的更多信息,见以下例子.

### 标签选项示例

如果应用程序是代码修改, 您可以替换标签 :

```js
const options = {
  aAnnotation: 'Original',
  bAnnotation: 'Modified',
};
```

```diff
- Original
+ Modified

  common
- changed from
+ changed to
```

这个 `jest-diff` 软件包不假定两个标签的长度相等.

### 已更改行的颜色选项示例

为了与大多数diff工具保持一致,您可以交换颜色:

```ts
import chalk from 'chalk';

const options = {
  aColor: chalk.red,
  bColor: chalk.green,
};
```

### 已更改子字符串的颜色选项示例

虽然对已更改的子字符串来说, 前景和背景颜色的默认反向很难击败 **在行内**,特别是因为它突出空格,如果您想要在黄色背景颜色上加粗体字体重:

```ts
import chalk from 'chalk';

const options = {
  changeColor: chalk.bold.bgYellowBright,
};
```

### 格式化后缀空格的选项示例

因为 `diff()` 不在行内显示下行差异,格式化可以帮助您看到,当行因存在或缺少后行空格而出现差异时 `/\s+$/` 正则表达式.

-   如果修改行有背景颜色,则可以看到后方的空格.
-   如果常见行带有默认暗色,则无法看到后方空格。 你可能希望黄色的背景颜色看到它们.

```js
const options = {
  aColor: chalk.rgb(128, 0, 128).bgRgb(255, 215, 255), // magenta
  bColor: chalk.rgb(0, 95, 0).bgRgb(215, 255, 215), // green
  commonLineTrailingSpaceColor: chalk.bgYellow,
};
```

色彩选项的值是一个函数,它给出了字符串,返回字符串.

如果您想要用中点字符替换后端空格 :

```js
const replaceSpacesWithMiddleDot = string => '·'.repeat(string.length);

const options = {
  changeLineTrailingSpaceColor: replaceSpacesWithMiddleDot,
  commonLineTrailingSpaceColor: replaceSpacesWithMiddleDot,
};
```

如果您需要颜色选项的类型脚本 :

```ts
import {DiffOptionsColor} from 'jest-diff';
```

### 无颜色选项示例

要将差异存储在文件中, 不为颜色设置逃生代码, 提供身份功能 :

```js
const noColor = string => string;

const options = {
  aColor: noColor,
  bColor: noColor,
  changeColor: noColor,
  commonColor: noColor,
  patchColor: noColor,
};
```

### 指标备选方案实例

与《公约》保持一致 `diff` 命令,您可以替换指标 :

```js
const options = {
  aIndicator: '<',
  bIndicator: '>',
};
```

这个 `jest-diff` 一揽子假设(但不执行)3个指标的长度相等.

### 限制常见行的选项示例

默认情况下,输出包括所有常见行.

为了强调这些变化,你可能会限制常见的“文字”行的数目:

```js
const options = {
  contextLines: 1,
  expand: false,
};
```

类似补丁标记 `@@ -12,7 +12,9 @@` 用于省略的普通行.

### 补丁标记颜色选项示例

如果您希望补丁标记的颜色与常见行相同:

```ts
import chalk from 'chalk';

const options = {
  expand: false,
  patchColor: chalk.dim,
};
```

### 包含更改计数的选项示例

在注释行右侧显示更改行数 :

```js
const a = ['common', 'changed from'];
const b = ['common', 'changed to', 'insert'];

const options = {
  includeChangeCounts: true,
};

const difference = diff(a, b, options);
```

```diff
- Expected  - 1
+ Received  + 2

  Array [
    "common",
-   "changed from",
+   "changed to",
+   "insert",
  ]
```

### 删除注释行的选项示例

只显示比较线:

```js
const a = 'common\nchanged from';
const b = 'common\nchanged to';

const options = {
  omitAnnotationLines: true,
};

const difference = diffStringsUnified(a, b, options);
```

```diff
  common
- changed from
+ changed to
```

### 空出第一行或最后一行的选项示例

如果 **第一个** 或者说 **最后一个** 比较线是 **空**,因为内容是空的,指示器是空的,所以你可能不会注意到它.

替换选项是默认值为 `''` 空字符串.

因为Jest在匹配器失败时会剪切报告,所以删除了一行空的最后一行.

因此,杰斯特将下行箭头和左角作为占位符:

```js
const options = {
  emptyFirstOrLastLinePlaceholder: '↵', // U+21B5
};
```

如果一个内容行是空的,那么相应的比较行会自动被修剪去除默认指标的比值空间(下面作为中间点表示):

| 指标 | 未调整 | 修剪 |
| --: | :-- | :-- |
| `aIndicator` | `'-·'` | `'-'` |
| `bIndicator` | `'+·'` | `'+'` |
| `commonIndicator` | `' ·'` | `''` |

### 排序对象密钥的选项示例

当比较两个对象时,默认按字母顺序打印它们的密钥. 如果这不是密钥的原始顺序, diff 将更难被读取, 因为密钥不在其原始位置 .

使用 `compareKeys` 来传递一个在排序对象密钥时使用的函数.

```js
const a = {c: 'c', b: 'b1', a: 'a'};
const b = {c: 'c', b: 'b2', a: 'a'};

const options = {
  // The keys will be in their original order
  compareKeys: () => 0,
};

const difference = diff(a, b, options);
```

```diff
- Expected
+ Received

  Object {
    "c": "c",
-   "b": "b1",
+   "b": "b2",
    "a": "a",
  }
```

视实施情况而定 `compareKeys` 任意排序顺序都可以使用.

```js
const a = {c: 'c', b: 'b1', a: 'a'};
const b = {c: 'c', b: 'b2', a: 'a'};

const options = {
  // The keys will be in reverse order
  compareKeys: (a, b) => (a > b ? -1 : 1),
};

const difference = diff(a, b, options);
```

```diff
- Expected
+ Received

  Object {
    "a": "a",
-   "b": "b1",
+   "b": "b2",
    "c": "c",
  }
```

## 常见问题

### jest-diff 是什么？

清晰显示差异,以便人们可以自信地审查变化\.

### 如何安装 jest-diff？

在项目目录运行 npm install jest-diff，或使用 pnpm add / yarn add / bun add。

### jest-diff 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### jest-diff 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### jest-diff 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^18\.14\.0 \|\| ^20\.0\.0 \|\| ^22\.0\.0 \|\| \>=24\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### jest-diff 可以商用吗？

jest-diff 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### jest-diff 的下载量有多少？

根据 npm 官方下载统计，jest-diff 在 2026/10/05 – 2026/11/03 这 30 天内被下载 305,354,739 次，日均约 10,178,491 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### jest-diff 还在维护吗？

最新版本 30\.5\.2 发布于 2026/09/18（1 个月前）；至今共发布 255 个版本，其中过去 12 个月发布了 6 个；首次发布于 2016/07/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。