# @blazediff/core-native 中文文档 规范地址：https://npmcn.com/package/%40blazediff/core-native/ 版本：7\.0\.0 npm 元数据更新时间：2026-11-05T04:23:39.899Z 中文译文更新时间：2026-11-08T06:25:39.993Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40blazediff/core-native 原文对照：https://npmcn.com/package/%40blazediff/core-native/?lang=original 项目主页：https://blazediff.dev/ 源码仓库：https://github.com/teimurjan/blazediff ## 关键信息（来自 npm 元数据） - 包体积（解压后）：38.2 kB，6 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：1 个 - 首次发布：2026-03-12T05:45:17.378Z - 最新版本发布：2026-11-05T04:23:39.550Z - 近 30 天下载量：19974（2026-10-09 至 2026-11-07，npm 官方下载统计） - 已发布版本数：17（近 12 个月 17 个） ## 中文简介 原始 Rust 二进制 Blazediff - 世界上最快的图像 diff ## 安装 ```sh npm install @blazediff/core-native ``` 也可以使用：`pnpm add @blazediff/core-native`、`yarn add @blazediff/core-native`、`bun add @blazediff/core-native` ## README # @ blazediff/ 核心本地化 [![npm bundle size](https://img.shields.io/npm/unpacked-size/%40blazediff%2Fcore-native?style=for-the-badge)](https://www.npmjs.com/package/@blazediff/core-native) [![NPM Downloads](https://img.shields.io/npm/dy/%40blazediff%2Fcore-native?style=for-the-badge)](https://www.npmjs.com/package/@blazediff/core-native) [![Crates.io](https://img.shields.io/crates/v/blazediff.svg?style=for-the-badge)](https://crates.io/crates/blazediff) 世界最快单行道图像 diff. 原始 Rust 执行中 SIMD 优化, **4.4-4.9x 较快** 财务报告和审定财务报表 **3个较小** 比起来 [缩写](https://github.com/dmtrKovalenko/odiff)。 。 。 . **特征 :** - **PNG, JPEG 和 QOI 支持** - 通过文件扩展或编码字节自动检测 - SIMD 加速(NEON on ARM,SSE4.1 on x86) - 基于块的双通最优化 - YIQ 透视颜色差异 - 防盗用检测 - 跨平台预建二进制(~700KB-900KB,不需要编译) **销售图书馆:** - [双簧管](https://libspng.org/) - 用SIMD(默认)快速PNG解码/编码 - [蓝色涡轮](https://libjpeg-turbo.org/) - 高性能 JPEG 编码器与 SIMD - [小强](https://github.com/aldanor/qoi-rust) - QOI(相当好图像)格式,用于快速无损压缩 > **实验 PNG 编码 :** 二进制还捆绑了内部的 Rust PNG 编码器 (单位:千美元)[`blazediff-png`](https://github.com/teimurjan/blazediff/tree/main/crates/blazediff-png), (中文(简体) ), 速度比每个固定点都快 字节解码对等 选入: 设定 `BLAZEDIFF_PNG_ENABLED=1` 来路由 PNG 解码和存储块( 0级) 编码 通过它。 spng 保持默认值 . > **说明:** 此软件包先前作为 [`@blazediff/bin`](https://www.npmjs.com/package/@blazediff/bin),现在已贬值。 请使用 `@blazediff/core-native` 换句话说. ## 安装 ```bash npm install @blazediff/core-native ``` 也可作为碎屑箱提供: [`cargo install blazediff`](https://crates.io/crates/blazediff) 预建的二进制通过特定平台包包含: - [`@blazediff/core-native-darwin-arm64`](https://github.com/teimurjan/blazediff/tree/main/packages/core-native/core-native-darwin-arm64) - macOS ARM64(苹果硅) - [`@blazediff/core-native-darwin-x64`](https://github.com/teimurjan/blazediff/tree/main/packages/core-native/core-native-darwin-x64) - macOS x64(英特尔) - [`@blazediff/core-native-linux-arm64`](https://github.com/teimurjan/blazediff/tree/main/packages/core-native/core-native-linux-arm64) - Linux ARM64号卫星 - [`@blazediff/core-native-linux-x64`](https://github.com/teimurjan/blazediff/tree/main/packages/core-native/core-native-linux-x64) - Linux x64 (英语) - [`@blazediff/core-native-win32-arm64`](https://github.com/teimurjan/blazediff/tree/main/packages/core-native/core-native-win32-arm64) - 视窗ARM64 - [`@blazediff/core-native-win32-x64`](https://github.com/teimurjan/blazediff/tree/main/packages/core-native/core-native-win32-x64) - 视窗x64 ## API 密码 ### diff( a, b, 选项) 比较两个图像并选择绘制 diff . `options` 实值 `@blazediff/core`是因为 `DiffOptions`更宽 `output`。 。 。 . | 参数 | 类型 | 说明 | | --- | --- | --- | | `a`, (中文(简体) ), `b` | 字符串 QQ Uint8Array 图像 | 文件路径, 编码了 PNG, JPEG 或 QOI 字节( a) `Buffer` ,或原始 RGBA 像素 `{ data, width, height }`。双方可以使用不同的类型 | | `options` | 本地选择 | 比较选项( 可选) | **回返情况:** `Promise` | 选项 | 类型 | 默认 | 说明 | | --- | --- | --- | --- | | `threshold` | 编号 | 0.1 数据 | 颜色差阈值 (0-1). 下调更严格 | | `antialiasing` | 布尔 | 真实 | 检测出反变相像素, 并把它们从数中排除 | | `metric` | "yiq" \\"oklab" (俄克利亚语) | "对" | 颜色相差度量. `oklab` 给出与像素匹配 8 相同的计数 | | `mask` | Uint8 阵列 | \- 说吧 | 每个像素一个字节(宽×高). 非零像素被跳过 。 需要 N- API 绑定 | | `window` | 编号 | \- 说吧 | 同时报告最diff像素的 NxN 窗口 | | `output` | 字符串 QQ 图像 {{{路径、压缩?、质量?} | \- 说吧 | 绘制 diff: 文件( PNG 压缩 0- 9, JPEG 质量 1- 100), 或 `Image` 填就绪。 图像完全相同时不写入文件 。 一个 `Image` 总是充满 | | `render` | 阿尔法 迪夫克洛尔 迪夫克洛尔 阿尔特 | \- 说吧 | 输出造型. `background: "transparent"` 独自绘制 diff | ### 结果类型 ```typescript type NativeDiffResult = | { kind: "compared"; count: number; percentage: number; identical: boolean; /** Top-left corner and count of the busiest window, when `window` is set. */ window?: { x: number; y: number; count: number }; } | { kind: "dimension-mismatch"; a: Size; b: Size } | { kind: "io-error"; path?: string; message: string }; ``` 无效的选项或缓冲器 `BlazeDiffError` (从 `@blazediff/core`带有 `code`数字 : `invalid-image`, (中文(简体) ), `invalid-output`, (中文(简体) ), `invalid-mask` 或者说 `invalid-option`。 。 。 . #### 编码缓冲输入 ```typescript import { readFile } from "node:fs/promises"; import { diff } from "@blazediff/core-native"; const [expected, actual] = await Promise.all([ readFile("expected.png"), readFile("actual.png"), ]); const result = await diff(expected, actual, { output: "diff.png" }); ``` 本地绑定借用已有的 `Buffer` 或者说 `Uint8Array` 支持同步呼叫的内存 。 被编码的字节没有被复制到Rust中,因此,同样的JavaScript缓冲器可以通过比较再用. 解码仍然会分配本地的RGBA像素缓冲. #### CLI 倒计时 如果N-API绑定无法装入, `diff` 运行捆绑 `blazediff` CLI(英语:CLI). 后退仅取路径输入和路径输出, 不 `mask`任何其它东西. ## 使用量 ### 程序化 API ```typescript import { diff } from '@blazediff/core-native'; const result = await diff('expected.png', 'actual.png', { output: 'diff.png', threshold: 0.1, }); if (result.kind === 'compared') { if (result.identical) console.log('Images are identical!'); else console.log(`${result.count} pixels differ (${result.percentage.toFixed(2)}%)`); } else if (result.kind === 'dimension-mismatch') { console.log('Images have different dimensions'); } else { console.log(`Could not read ${result.path}: ${result.message}`); } ``` ### 描述已改变的东西 此软件包的答案 _地点_ 两个图像不同。 对于 _什麽_ 更改——标签 区域、变化类型、严重程度和人可读摘要——使用 [`@blazediff/interpret-native`](https://www.npmjs.com/package/@blazediff/interpret-native), (中文(简体) ), 以 SSIM 映射或 框中已经包含. ```typescript import { interpret } from '@blazediff/interpret-native'; const result = await interpret('expected.png', 'actual.png', 'diff.png'); console.log(result.summary); console.log(`Severity: ${result.severity}, ${result.diffPercentage.toFixed(2)}% changed`); ``` ### CLI 使用量 ```bash # Compare two PNG images npx blazediff expected.png actual.png -o diff.png # Compare two JPEG images npx blazediff expected.jpg actual.jpg -o diff.jpg # Mixed formats (PNG input, QOI output - recommended for smallest diff files) npx blazediff expected.png actual.png -o diff.qoi # With options npx blazediff expected.png actual.png -o diff.png --threshold 0.05 --no-antialiasing # pixelmatch 8 metric, a mask, and the busiest 16×16 window npx blazediff expected.png actual.png --metric oklab --mask mask.png --window 16 # With higher PNG compression (smaller output file, slower) npx blazediff expected.png actual.png -o diff.png -c 6 # Output as JSON npx blazediff expected.png actual.png --json ``` ### CLI 选项 ``` Usage: blazediff [OPTIONS] Arguments: First image path (PNG, JPEG, or QOI) Second image path (PNG, JPEG, or QOI) Options: -o, --output Write the diff image (only when the images differ) -t, --threshold Color difference threshold (0.0-1.0) [default: 0.1] --antialiasing Detect anti-aliased pixels and leave them out of the count (default) --no-antialiasing Count anti-aliased pixels as differences --metric Color difference metric: yiq or oklab (pixelmatch 8) [default: yiq] --mask Image the size of the inputs; its non-black pixels are skipped --window Also report the N×N window with the most diff pixels -a, --alpha Opacity of the faded background (0.0-1.0) [default: 0.1] --diff-color RGB color for differing pixels --diff-color-alt RGB color for pixels that get darker in the second image --aa-color RGB color for anti-aliased pixels --background faded or transparent [default: faded] -c, --compression PNG compression level (0-9, 0=fastest, 9=smallest) [default: 0] -q, --quality JPEG quality (1-100) [default: 90] --json Print the result as JSON -h, --help Print help -V, --version Print version ``` 与 `--json`,结果对象打印到 stdout 和诸如 `{"kind":"io-error","path":"...","message":"..."}` 打印为 stderr . ### 支持的格式 | 格式 | 扩展 | 页:1 | | --- | --- | --- | | 巴布亚新几内亚 | `.png` | 无损失,支持透明度 | | JPEG 组合 | `.jpg`, (中文(简体) ), `.jpeg` | 丢失, 文件大小较小 | | 问 题 | `.qoi` | 快速无损, 理想的 diff 输出( 12x 小于未压缩的 PNG) | 输入图像可以是混合格式(例如比较PNG和JPEG). 输出格式由输出文件扩展名决定. **Diff 输出的QOI :** QOI擅长将diff图像编码为大同域,生成比PNG(0级)更小的12x文件,同时更快地编码. ### 退出代码 - `0` - 图像是相同的 - `1` - 图像不同,或者其尺寸不匹配 - `2` - 出错(文件未找到,格式无效等) ## 业绩 以Apple M1 Max(25跑,5热身,包括图像 IO)为基准,反对 `odiff` 4K PNG 图像通过 `hyperfine`根中的全部数字 [银行](https://github.com/teimurjan/blazediff/blob/main/BENCHMARKS.md)。 。 。 . | 工具 | 4k/1 (单位:千美元) | 4k/2 (韩语) | 4k/3 (单位:千美元) | 轻而易举 | | --- | --- | --- | --: | --- | | **光线** | ~275ms (英语) | ~342ms (单位:千米) | ~347 ms (单位:千米) | \- 说吧 | | **光线** (编码缓冲输入) | ~203ms (单位:千米) | 256ms( 256ms) 坐标 | 约270ms | \- 说吧 | | 缩写 | ~1266ms (英语) | ~1538ms 时 | ~1799ms (英语) | 4.5-5.2x 慢点 | 二进制大小( 斜拉, LTO 优化) - **~3x 小于食道**数字 : | 平台 | 光线 | 缩写 | | --- | --- | --- | | 马科斯ARM64 | 702 KB (韩语) | 2.2 甲基溴 | | macOS x64 | 773 KB (韩语) | 2.6 甲基溴 | | Linux ARM64 软件 | 753个KB | 2.3 甲基溴 | | Linux x64 函数 | 869 KB (英语) | 2.9 甲基溴 | | 窗口 ARM64 | 580 KB 车次 | 2.4 甲基溴 | | 视窗 x64 | 915个KB | 3.0 MB (英语) | ## 算法 BlazeDiff采用双通区块方式,并有SIMD加速: 1. **冷传**: 使用32位整数比较扫描8x8块的图像,以识别已改变的区域 2. **热传**: 只应用 YIQ 感知颜色差异标记的流程块 3. **锡默德**: 使用近地物体N(ARM)或SSE4.1(x86)进行平行像素处理 4. **反亵渎**: 执行Vysniauskas(2009年)算法来检测AA文物 ## 参考资料 - **YIQ 颜色空间**数字 : [科萨连科和拉莫斯(2009年)](https://doaj.org/article/b2e3b5088ba943eebd9af2927fef08ad) - “利用YIQ NTSC传输色相空间测量可见的颜色差异” - **反干扰检测**数字 : [维斯尼亚卡斯(2009年)](https://www.researchgate.net/publication/234073157_Anti-aliased_Pixel_and_Intensity_Slope_Detector) - "反异形像素和强度斯洛普探测器" - **灵感**数字 : [缩写](https://github.com/dmtrKovalenko/odiff) - 用 Zig 写的快速图像比较工具 ## 常见问题 ### @blazediff/core-native 是什么？ 原始 Rust 二进制 Blazediff - 世界上最快的图像 diff ### 如何安装 @blazediff/core-native？ 在项目目录运行 npm install @blazediff/core-native，或使用 pnpm add / yarn add / bun add。 ### @blazediff/core-native 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @blazediff/core-native 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @blazediff/core-native 可以商用吗？ @blazediff/core-native 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @blazediff/core-native 的下载量有多少？ 根据 npm 官方下载统计，@blazediff/core-native 在 2026/10/09 – 2026/11/07 这 30 天内被下载 19,974 次，日均约 666 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @blazediff/core-native 还在维护吗？ 最新版本 7\.0\.0 发布于 2026/11/05（3 天前）；至今共发布 17 个版本，其中过去 12 个月发布了 17 个；首次发布于 2026/03/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。