# @adguard/diff-builder 中文文档

规范地址：https://npmcn.com/package/%40adguard/diff-builder/

版本：1\.1\.9
npm 元数据更新时间：2026-10-01T11:12:48.301Z
中文译文更新时间：2026-11-06T00:48:30.580Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40adguard/diff-builder
原文对照：https://npmcn.com/package/%40adguard/diff-builder/?lang=original
项目主页：https://github.com/AdguardTeam/DiffBuilder#readme
源码仓库：https://github.com/AdGuardSoftwareLimited/ext-diff-builder

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

- 包体积（解压后）：329 kB，26 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- 首次发布：2023-12-19T14:24:10.599Z
- 最新版本发布：2026-10-01T11:12:48.089Z
- 近 30 天下载量：7832（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 6 个）

## 中文简介

为过滤列表生成差异更新的工具 .

## 安装

```sh
npm install @adguard/diff-builder
```

也可以使用：`pnpm add @adguard/diff-builder`、`yarn add @adguard/diff-builder`、`bun add @adguard/diff-builder`

## README

# 守护 Diff 构建器

`@adguard/diff-builder` 是 npm 软件包,用于生成和应用 添加屏蔽过滤列表的差别更新 。 而不是重新下载 每次更新时, 服务器都会产生一个紧凑的 RCS 格式补丁 对于每个版本,客户端只获取它尚未获取的补丁 应用.

> **说明:** 此软件包开发于 [辅助软件](https://github.com/AdGuardSoftwareLimited/ext-diff-builder)。 。 。 . 这个 [守护小组/ diffBuilder](https://github.com/AdguardTeam/DiffBuilder) 寄存器是一个公共镜像.

货包载有两个独立的API和一个CLI:

-   **`DiffBuilder`** ——服务器侧 (Node.js / CI): 比较两个过滤器 修改, 撰写补丁文件, 并管理补丁目录 .
-   **`DiffUpdater`** ——客户端(Node.js或浏览器):正在获取 从 URL 补丁并将其应用到本地存储的过滤器上.
-   **`diff-builder` 国 际** - 包装 `DiffBuilder` 用于 shell 脚本和 CI管道.

## 目录

-   [关键概念](https://npmcn.com/package/%40adguard/diff-builder/#readme-key-concepts)
-   [安装](https://npmcn.com/package/%40adguard/diff-builder/#readme-installation)
-   [快速启动](https://npmcn.com/package/%40adguard/diff-builder/#readme-quick-start)
-   [CLI 参考](https://npmcn.com/package/%40adguard/diff-builder/#readme-cli-reference)
-   [API 参考](https://npmcn.com/package/%40adguard/diff-builder/#readme-api-reference)
    -   [DiffBuilder(节点.js)](https://npmcn.com/package/%40adguard/diff-builder/#readme-diffbuilder-nodejs)
    -   [DiffUpdater (Node.js / 浏览器) (中文(简体) )](https://npmcn.com/package/%40adguard/diff-builder/#readme-diffupdater-nodejs--browser)
-   [文档](https://npmcn.com/package/%40adguard/diff-builder/#readme-documentation)

## 关键概念

**过滤列表** ——包含广告屏蔽规则的平文文件. 每个 已公布的修订版是文件的快照.

**RCS 补丁** - 一个紧凑的diff英寸 [RCS 格式](https://www.gnu.org/software/diffutils/manual/diffutils.html#RCS) 编码两个连续过滤器修改之间的变化。 客户 依次应用补丁,以从以往的任何修订推进到当前 一个不下载完整文件.

**补丁名称** ——每个补丁文件被命名,以便其元数据可以被解码 不读取文件 :

```text
<name>[-<resolution>]-<epochTimestamp>-<expirationPeriod>.patch
```

-   `name` ——任意标识字符串 (1-64个字符,无空格).
-   `resolution` 两个数字字段的可选时间单位: `h` (小时, 默认), `m` (分钟), `s` (秒数).
-   `epochTimestamp` ——补丁创建时间,在所选的解析中.
-   `expirationPeriod` ——补丁是否有效,在所选的解析中.

**`Diff-Path` 标签** —— 写入过滤文件的元数据行 客户端补丁目录的 URL :

```text
! Diff-Path: https://example.com/filters/patches/v1.2.3-m-28334060-60.patch
```

`DiffBuilder` 自动添加并更新此标签 . `DiffUpdater` 读出来 以发现要获取补丁的地方.

**校对和** - 嵌入在补丁中的可选 SHA-1 散列 `diff` 指令。 现在, `DiffUpdater` 之后验证过滤器内容 如果散列不匹配,则应用补丁并拒绝.

## 安装

**运行时间要求 :**

-   [节点.js](https://nodejs.org/en/download) v20 或更高( 对于构建器和 CLI; 更新器也在其中运行) 浏览器).
-   调和 `diff` 工具( 运行时由构建者需要) :
    -   macOS - 默认可用,或通过 `xcode-select --install`。 。 。 .
    -   Linux - 默认可用,或 `apt-get install diffutils`。 。 。 .
    -   Windows – 在 WSL 或 Git Bash 中可用.

**在您的项目中添加:**

```bash
npm install @adguard/diff-builder
# or
pnpm add @adguard/diff-builder
```

## 快速启动

### 生成补丁( 服务器 / CI)

```bash
# CLI: compare old_filter.txt → new_filter.txt, write patch to patches/
diff-builder build \
    -n my-filter \
    -t 60 \
    -r m \
    old_filter.txt \
    new_filter.txt \
    patches/
```

### 应用补丁(客户端)

```javascript
import { DiffUpdater } from '@adguard/diff-builder/diff-updater/es';

const updatedFilter = await DiffUpdater.applyPatch({
    filterUrl: 'https://example.com/filters/filter.txt',
    filterContent: currentFilterText,
});
```

## CLI 参考

```text
diff-builder build [options] <old_filter> <new_filter> <path_to_patches>
```

**立场参数 :**

| 参数 | 说明 |
| --- | --- |
| `<old_filter>` | 上一个过滤器修改的路径 . |
| `<new_filter>` | 新过滤器修改路径 。 文件在新位置更新 `Diff-Path` 标签. |
| `<path_to_patches>` | 存储补丁文件的目录 。 若不存在则创建. |

**选项 :**

| 选项 | 需求 | 说明 |
| --- | --- | --- |
| `-n, --name <name>` | 对 | 补丁标识符:1–64个字符,没有空格或特殊字符. |
| `-t, --time <expirationPeriod>` | 对 | 补丁有效时间, 单位: `--resolution`。 。 。 . |
| `-r, --resolution <h|m|s>` | 没有 | 时间单位 `--time` 和嵌入式时间戳 : `h` 小时(默认), `m` 分钟, `s` 秒数. |
| `-c, --checksum` | 没有 | 在补丁中嵌入后页过滤内容的 SHA-1 校验和. |
| `-d, --delete-older-than-sec <seconds>` | 没有 | 删除超过此数秒的非空补丁文件 。 默认 : `604800` (7天) (中文(简体) ). |
| `--max-patch-size <bytes>` | 没有 | 以字节表示的最大补丁大小 。 跳过补丁并省略 `Diff-Path` (默认 1 MB). |
| `-v, --verbose` | 没有 | 打印进度消息到 stdout . |

**示例——带有校验和验证的60分钟补丁:**

```bash
diff-builder build \
    -n adguard-base \
    -t 60 \
    -r m \
    -c \
    -v \
    filters/base_old.txt \
    filters/base.txt \
    filters/patches/
```

## API 参考

### DiffBuilder(节点.js)

从两个过滤器修改生成补丁文件并管理补丁 目录。 需要节点和系统 `diff` 函数.

#### 司法理事会

```javascript
const { DiffBuilder } = require('@adguard/diff-builder');
```

#### 无害环境管理

```javascript
import { DiffBuilder } from '@adguard/diff-builder/es';
```

#### `DiffBuilder.buildDiff(params)`

```javascript
await DiffBuilder.buildDiff({
    oldFilterPath,   // string — path to the previous filter revision
    newFilterPath,   // string — path to the new filter revision (updated in-place)
    patchesPath,     // string — directory to read/write patch files
    name,            // string — patch identifier (1–64 chars, no spaces)
    time,            // number — expiration period in units of `resolution`
    resolution,      // 'h' | 'm' | 's' — time unit (default: 'h')
    checksum,        // boolean — embed SHA-1 checksum (default: false)
    deleteOlderThanSec, // number — TTL for old patches in seconds (default: 604800)
    maxPatchSize,    // number — max patch size in bytes (default: 1048576)
    verbose,         // boolean — print progress messages (default: false)
});
```

被调用时:

1.  如果两个过滤器之间没有有意义的变化,则函数退出 不写任何文件.
2.  否则会在其中创建新补丁文件 `patchesPath`,更新 `Diff-Path` 标记在 `newFilterPath`,并删除已过期的补丁.
3.  如果生成的补丁大于 `maxPatchSize`,没有写到: 页:1 `Diff-Path` 标记未添加到 `newFilterPath`空占位符 补丁从 `patchesPath`。 。 。 .

**错误 :**

-   如果生成的补丁失败自我验证, 则拒绝 : 补丁不能是 应用到旧过滤器,或者补丁的旧过滤器与新过滤器不同 一个 基本错误作为 `cause`。 。 。 .
-   新过滤器和补丁文件在拒绝时没有写入; 已过期 补丁可能已被删除 .

### DiffUpdater (Node.js / 浏览器) (中文(简体) )

获取并应用待补补补丁将本地存储的过滤器带入 约会。 与 Node.js 和浏览器环境兼容——不使用 `fs`, (中文(简体) ), `path`,或 `child_process`。 。 。 .

#### 司法理事会

```javascript
const { DiffUpdater } = require('@adguard/diff-builder/diff-updater');
```

#### 无害环境管理

```javascript
import { DiffUpdater } from '@adguard/diff-builder/diff-updater/es';
```

#### `DiffUpdater.applyPatch(params)`

```javascript
const updatedFilter = await DiffUpdater.applyPatch({
    filterUrl,      // string — URL of the filter file (used to resolve patch URLs)
    filterContent,  // string — current filter text stored by the client
    verbose,        // boolean — print progress messages (default: false)
});
// Returns the updated filter content as a string.
```

职能:

1.  读取 `Diff-Path` 标记来自 `filterContent` 找到补丁 目录.
2.  在 URL 获取补丁文件 。 如果服务器返回 204 或 404 过滤器已经是当前和原始的 `filterContent` 已返回 不变.
3.  从补丁应用 RCS 操作到 `filterContent`。 。 。 .
4.  如果补丁包含校验和, 则验证结果并丢出 不符合.
5.  读取新的 `Diff-Path` 标记从更新的内容并重复到 没有其他补丁.

**错误 :**

-   掷出 `UnacceptableResponseError` 如果服务器返回 HTTP 状态 200、204或404除外.
-   丢出通用 `Error` 如果一个补丁形状不当或检查和校验 失败.

```javascript
import {
    DiffUpdater,
    UnacceptableResponseError,
} from '@adguard/diff-builder/diff-updater/es';

try {
    const updated = await DiffUpdater.applyPatch({ filterUrl, filterContent });
} catch (err) {
    if (err instanceof UnacceptableResponseError) {
        // Network/server error — handle or retry
    }
    throw err;
}
```

## 文档

-   [发展](https://npmcn.com/package/%40adguard/diff-builder/DEVELOPMENT.md)
-   [部署](https://npmcn.com/package/%40adguard/diff-builder/DEPLOYMENT.md)
-   [更改日志](https://npmcn.com/package/%40adguard/diff-builder/CHANGELOG.md)
-   [LLM 代理规则](https://npmcn.com/package/%40adguard/diff-builder/AGENTS.md)

## 常见问题

### @adguard/diff-builder 是什么？

为过滤列表生成差异更新的工具 \.

### 如何安装 @adguard/diff-builder？

在项目目录运行 npm install @adguard/diff-builder，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 diff-builder，可以用 npx diff-builder 直接运行。

### @adguard/diff-builder 支持 TypeScript 吗？

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

### @adguard/diff-builder 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @adguard/diff-builder 需要什么版本的 Node\.js？

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

### @adguard/diff-builder 可以商用吗？

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

### @adguard/diff-builder 的下载量有多少？

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

### @adguard/diff-builder 还在维护吗？

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