# @flatfile/plugin-dedupe 中文文档

规范地址：https://npmcn.com/package/%40flatfile/plugin-dedupe/

版本：1\.5\.1
npm 元数据更新时间：2026-04-23T23:54:40.525Z
中文译文更新时间：2026-11-14T22:47:55.540Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%40flatfile/plugin-dedupe
原文对照：https://npmcn.com/package/%40flatfile/plugin-dedupe/?lang=original
项目主页：https://github.com/FlatFilers/flatfile-plugins#readme
源码仓库：https://github.com/FlatFilers/flatfile-plugins

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

- 包体积（解压后）：52.9 kB，12 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 18
- 运行依赖：2 个
- peer 依赖：@flatfile/api ^1\.9\.19，@flatfile/listener ^1\.1\.0
- 首次发布：2023-08-08T19:07:04.348Z
- 最新版本发布：2024-12-19T22:29:48.008Z
- 近 30 天下载量：2374（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 0 个）

## 中文简介

Dedupe 通过工作表关卡自定义动作在工作表中记录 .

## 安装

```sh
npm install @flatfile/plugin-dedupe
```

也可以使用：`pnpm add @flatfile/plugin-dedupe`、`yarn add @flatfile/plugin-dedupe`、`bun add @flatfile/plugin-dedupe`

## README

此插件通过工作表级别动作在工作表中记录 .

**事件类型 :** `listener.on('job:ready')`

> 嵌入Flatfile时,该插件应被部署在服务器侧听器中. [学多点](https://npmcn.com/docs/orchestration/listeners#listener-types)

## 参数

#### `jobOperation` - 说吧 `string` - (必须)

这个 `jobOperation` 参数指定要匹配的任务操作的名称.

#### `opt.on` - 说吧 `string`

这个 `on` 参数指定要匹配的字段密钥.

#### `opt.keep` - 说吧 `'first' | 'last'`

这个 `keep` 选项允许您选择是保留第一个还是最后一个重复记录.

#### `opt.custom` - 说吧 `function()`

这个 `custom` 参数接受自定义去dupe函数。 这将覆盖 `keep` 参数.

#### `opt.debug` - 说吧 `boolean`

这个 `debug` 参数允许您为开发目的切换或关闭帮助调试消息.

## API 调用

-   `api.records.get`
-   `api.jobs.ack`
-   `api.records.delete`
-   `api.jobs.fail`
-   `api.jobs.complete`

## 使用量

必须在工作表上配置“ dedupe- email” 操作名的动作, 以启动插件 .

```bash
npm i @flatfile/plugin-dedupe
```

```js
import { dedupePlugin } from "@flatfile/plugin-dedupe";
```

```ts
import { Flatfile } from '@flatfile/api'

export const contactsSheet: Flatfile.SheetConfig = {
  name: 'Contacts',
  slug: 'contacts',
  fields: [
    {
      key: 'firstName',
      type: 'string',
      label: 'First Name',
    },
    {
      key: 'lastName',
      type: 'string',
      label: 'Last Name',
    },
    {
      key: 'email',
      type: 'string',
      label: 'Email',
    }
  ],
  // Add a Sheet-level action here for the dedupe plugin
  actions: [
    {
      operation: "dedupe-email",
      mode: "background",
      label: "Dedupe emails",
      description: "Remove duplicate emails"
    }
  ]
}
```

### Java 脚本

#### 听众.js

```js
// common usage
// Keep the last record encountered (from top to bottom) based on the`email` field key.
// Must have a Sheet-level action specified with the operation name `dedupe-email`
listener.use(
  dedupePlugin("dedupe-email", {
    on: "email",
    keep: "last",
  })
);

// user specified dedupe function must return a list a record id's for deletion
listener.use(
  dedupePlugin("dedupe-email", {
    custom: (records) => {
      let uniques = new Set();
      let toDelete = [];

      records.forEach(record => {
        const { value } = record.values["email"];
        if (uniques.has(value)) {
          toDelete.push(record.id);
        } else {
          uniques.add(value);
        }
      });

      return toDelete;
    },
  })
);
```

### 类型脚本

#### 监听器

```ts
// common usage
// Keep the last record encountered (from top to bottom) based on the`email` field key.
// Must have a Sheet-level action specified with the operation name `dedupe-email`
listener.use(
  dedupePlugin("dedupe-email", {
    on: "email",
    keep: "last",
  })
);

// user specified dedupe function must return a list a record id's for deletion
listener.use(
  dedupePlugin("dedupe-email", {
    custom: (records: Flatfile.RecordsWithLinks) => {
      let uniques = new Set();
      let toDelete = [];

      records.forEach(record => {
        const { value } = record.values["email"];
        if (uniques.has(value)) {
          toDelete.push(record.id);
        } else {
          uniques.add(value);
        }
      });

      return toDelete;
    },
  })
);
```

## 常见问题

### @flatfile/plugin-dedupe 是什么？

Dedupe 通过工作表关卡自定义动作在工作表中记录 \.

### 如何安装 @flatfile/plugin-dedupe？

在项目目录运行 npm install @flatfile/plugin-dedupe，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@flatfile/api（^1\.9\.19）、@flatfile/listener（^1\.1\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @flatfile/plugin-dedupe 支持 TypeScript 吗？

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

### @flatfile/plugin-dedupe 支持 ESM 还是 CommonJS？

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

### @flatfile/plugin-dedupe 需要什么版本的 Node\.js？

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

### @flatfile/plugin-dedupe 可以商用吗？

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

### @flatfile/plugin-dedupe 的下载量有多少？

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

### @flatfile/plugin-dedupe 还在维护吗？

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