# @blazediff/matcher 中文文档

规范地址：https://npmcn.com/package/%40blazediff/matcher/

版本：3\.0\.0
npm 元数据更新时间：2026-11-05T04:23:29.849Z
中文译文更新时间：2026-11-08T06:28:06.552Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40blazediff/matcher
原文对照：https://npmcn.com/package/%40blazediff/matcher/?lang=original
项目主页：https://blazediff.dev/
源码仓库：https://github.com/teimurjan/blazediff

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

- 包体积（解压后）：50.5 kB，8 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：7 个
- 首次发布：2026-01-05T11:54:18.274Z
- 最新版本发布：2026-11-05T04:23:29.498Z
- 近 30 天下载量：13125（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：31（近 12 个月 31 个）

## 中文简介

使用 blazediff 进行视觉回归测试的核心匹配器逻辑

## 安装

```sh
npm install @blazediff/matcher
```

也可以使用：`pnpm add @blazediff/matcher`、`yarn add @blazediff/matcher`、`bun add @blazediff/matcher`

## README

# @ blazediff/ marcher (英语)

[![npm bundle size](https://img.shields.io/npm/unpacked-size/%40blazediff%2Fmatcher?style=for-the-badge)](https://www.npmjs.com/package/@blazediff/matcher) [![NPM Downloads](https://img.shields.io/npm/dy/%40blazediff%2Fmatcher?style=for-the-badge)](https://www.npmjs.com/package/@blazediff/matcher)

视觉回归测试的核心匹配者逻辑. 提供与多算法,框架不可知API,快取状态跟踪的快取比较.

## 特征

-   **多种比较方法**数字 : `core`, (中文(简体) ), `core-native`, (中文(简体) ), `ssim`, (中文(简体) ), `msssim`, (中文(简体) ), `hitchhikers-ssim`, (中文(简体) ), `gmsd`
-   **灵活输入类型**: 文件路径或图像缓冲
-   **快照状态跟踪**: 报告增加/匹配/更新/失效
-   **可配置阈值**: 按像素计数或百分比
-   **框架不可知性**: Jest, Vitest, Bun 集成的核心逻辑
-   **丰富的比较结果**: Diff 计数、百分比和相似性分数

## 安装

```bash
npm install @blazediff/matcher
```

## 快速启动

```typescript
import { getOrCreateSnapshot } from '@blazediff/matcher';

const result = await getOrCreateSnapshot(
  imageBuffer, // or file path
  {
    method: 'core',
    failureThreshold: 0.01,
    failureThresholdType: 'percent',
  },
  {
    testPath: '/path/to/test.spec.ts',
    testName: 'should render correctly',
  }
);

console.log(result.pass); // true/false
console.log(result.snapshotStatus); // 'added' | 'matched' | 'updated' | 'failed'
console.log(result.diffPercentage); // e.g., 0.05
```

## API 参考

### 获取 OrCreateSnapshot( 已收到, 选项, 测试Context)

用于快照比较的主要功能.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `received` | 图像输入 | 要比较的图像( 有尺寸的文件路径或缓冲) |
| `options` | 匹配选项 | 比较备选办法(见下文) |
| `testContext` | 测试语句 | 测试信息( testPath, 测试Name |

**回返情况:** `Promise<ComparisonResult>`

### 匹配选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `method` | 比较方法 | \- 说吧 | 要使用的比较算法 |
| `failureThreshold` | 编号 | 0 个 | 允许的像素数或百分比差异 |
| `failureThresholdType` | “ 像素”“%” | "像素"(像素) | 如何解释失败风险 |
| `snapshotsDir` | 字符串 | "... 弹出..." | 存储快照的目录( 相对于测试文件) |
| `snapshotIdentifier` | 字符串 | \- 说吧 | 自定义快照文件的标识符 |
| `updateSnapshots` | 布尔 | 虚假 | 强制更新快照( 如使用 - u 旗帜运行) |
| `diff` | Omit <diff 选项, “输出” > | \- 说吧 | `threshold`, (中文(简体) ), `antialiasing` (默认的), `metric`, (中文(简体) ), `mask`, (中文(简体) ), `window` 财务报告和审定财务报表 `render`。见 `@blazediff/core`用于核心、核心瓦斯和核心本土. |
| `ssim` | Omit < 模拟选项, "输出" > | \- 说吧 | `windowSize`, (中文(简体) ), `k1`, (中文(简体) ), `k2`, (中文(简体) ), `bitDepth`, (中文(简体) ), `msSsim` 财务报告和审定财务报表 `hitchhikers`。见 `@blazediff/ssim`用于sim,mssim和搭便车-sim. |
| `gmsd` | 输出 < Gmsd 选项, "输出" > | \- 说吧 | `downsample` 财务报告和审定财务报表 `c`。见 `@blazediff/gmsd`被gmsd使用过. |
| `runInWorker` | 布尔 | 真实 | 运行图像 I/ O 并用工人线程进行比较, 以便更好的性能 |

### 比较结果

| 外地 | 类型 | 说明 |
| --- | --- | --- |
| `pass` | 布尔 | 比较是否通过 |
| `message` | 字符串 | 描述结果的可读信息 |
| `snapshotStatus` | 快照状态 | 添加“ + ” “ 匹配 ” “ 更新 ” “ 失败 ” |
| `diffCount` | 编号 | 不同像素的数量(基于像素的方法) |
| `diffPercentage` | 编号 | 不同像素的百分比 |
| `score` | 编号 | 相似度分数(SSIM:1=同分,GMSD:0=同分) |
| `baselinePath` | 字符串 | 基线快照路径 |
| `receivedPath` | 字符串 | 收到图像的路径( 失败时调试时保存) |
| `diffPath` | 字符串 | Diff可视化路径 |

### 图像输入

```typescript
type ImageInput =
  | string // File path
  | Uint8Array // Encoded PNG bytes (a Buffer works)
  | {
      data: Uint8Array | Uint8ClampedArray | Buffer;
      width: number;
      height: number;
    };
```

## 比较方法

### `core-native`

通过 N-API 绑定来进行粗口比对. **最快速的方法** 与本地的表演.

-   **投入**: 文件路径、 PNG 缓冲器或原始 RGBA 图像
-   **算法**: YIQ 色彩空间, 基于块优化
-   **最好还是**: 生产测试,大图像

### `core-wasm`

这个 `core-native` 算法编译为 WebAssembly 。 同样的结果,没有本地的二进制.

-   **投入**: 文件路径或缓冲

### `core`

在JavaScript中比对像素. 纯粹的JS执行,没有本土依赖.

-   **投入**: 文件路径或缓冲
-   **算法**: YIQ 有反变异检测的色彩空间
-   **最好还是**: 跨平台相容性

### `ssim`

结构相似性指数. 衡量概念上的相似性.

-   **投入**: 文件路径或缓冲
-   **算法**: 具有可配置窗口大小的标准SSIM
-   **最好还是**: 概念质量评估
-   **分数**: 1 = 相同,下同

### `msssim`

多比例结构相似性指数.

-   **投入**: 文件路径或缓冲
-   **算法**: 跨多个尺度的SSIM
-   **最好还是**: 分辨率或比例不同的图像

### `hitchhikers-ssim`

快速SSIM取自"希契克指南".

-   **投入**: 文件路径或缓冲
-   **算法**: 优化SSIM计算
-   **最好还是**: 以可接受的精确度取舍加快SSIM

### `gmsd`

渐入相相相相相.

-   **投入**: 文件路径或缓冲
-   **算法**: 基于渐变的感官相似性
-   **最好还是**: 检测结构变化
-   **分数**: 0 = 相同,高 = 不同

## 用法实例

### 带有文件路径

```typescript
const result = await getOrCreateSnapshot(
  '/path/to/screenshot.png',
  { method: 'core-native' },
  { testPath: __filename, testName: 'test name' }
);
```

### 带有图像缓冲

```typescript
const imageData = {
  data: new Uint8Array([...]),
  width: 800,
  height: 600,
};

const result = await getOrCreateSnapshot(
  imageData,
  { method: 'core' },
  { testPath: __filename, testName: 'test name' }
);
```

### 自定义阈值

```typescript
const result = await getOrCreateSnapshot(
  imagePath,
  {
    method: 'core',
    failureThreshold: 0.1,
    failureThresholdType: 'percent', // Allow 0.1% difference
    diff: { threshold: 0.05 }, // Stricter per-pixel color threshold
  },
  { testPath: __filename, testName: 'test name' }
);
```

### 不同的比较方法

```typescript
// Fastest - Rust native (paths, PNG buffers or raw images)
await getOrCreateSnapshot(imagePath, { method: 'core-native' }, context);

// Pure JavaScript
await getOrCreateSnapshot(imageBuffer, { method: 'core' }, context);

// Perceptual similarity
await getOrCreateSnapshot(imageBuffer, { method: 'ssim' }, context);

// Gradient-based
await getOrCreateSnapshot(imageBuffer, { method: 'gmsd' }, context);
```

## 框架整合

这个软件包为特定框架的整合提供了核心逻辑:

-   [@blazediff/快讯](https://www.npmjs.com/package/@blazediff/jest) - 最佳配对者
-   [@ blazediff/vitest (英语)](https://www.npmjs.com/package/@blazediff/vitest) - 维特匹配者
-   [@ blazediff/ bun (英语)](https://www.npmjs.com/package/@blazediff/bun) - Bun测试匹配器

## 链接

-   [GitHub 仓库](https://github.com/teimurjan/blazediff)
-   [文档](https://blazediff.dev/docs/matcher)
-   [国家防范机制一揽子计划](https://www.npmjs.com/package/@blazediff/matcher)

## 常见问题

### @blazediff/matcher 是什么？

使用 blazediff 进行视觉回归测试的核心匹配器逻辑

### 如何安装 @blazediff/matcher？

在项目目录运行 npm install @blazediff/matcher，或使用 pnpm add / yarn add / bun add。

### @blazediff/matcher 支持 TypeScript 吗？

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

### @blazediff/matcher 支持 ESM 还是 CommonJS？

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

### @blazediff/matcher 可以商用吗？

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

### @blazediff/matcher 的下载量有多少？

根据 npm 官方下载统计，@blazediff/matcher 在 2026/10/09 – 2026/11/07 这 30 天内被下载 13,125 次，日均约 438 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @blazediff/matcher 还在维护吗？

最新版本 3\.0\.0 发布于 2026/11/05（3 天前）；至今共发布 31 个版本，其中过去 12 个月发布了 31 个；首次发布于 2026/01/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。