# @faapi/task-bullmq 中文文档

规范地址：https://npmcn.com/package/%40faapi/task-bullmq/

版本：7\.21\.0
npm 元数据更新时间：2026-10-31T23:22:43.358Z
中文译文更新时间：2026-11-01T03:11:43.739Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：85 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：0 个
- peer 依赖：bullmq ^6\.0\.0，@faapi/faapi ^7\.21\.0
- 首次发布：2026-09-13T05:10:55.716Z
- 最新版本发布：2026-10-31T23:22:43.042Z
- 已发布版本数：81（近 12 个月 81 个）

## 中文简介

Redis上faapi - persistent队列的BullMQ任务队列驱动程序

## 安装

```sh
npm install @faapi/task-bullmq
```

也可以使用：`pnpm add @faapi/task-bullmq`、`yarn add @faapi/task-bullmq`、`bun add @faapi/task-bullmq`

## README

# @faapi/task-bullmq

faapi 任务子系统的 **BullMQ 驱动**（Redis 持久化队列）。

基于 Redis 的任务队列——任务不丢（持久化）、多实例天然防重跑（worker 领取制）、支持延迟任务与指数退避重试。适合已有 Redis 基础设施或需要高吞吐的项目。

## 安装

```bash
pnpm add @faapi/task-bullmq bullmq ioredis
```

> bullmq 6 起 `ioredis` 由内置依赖移至 peer dependency——需业务方显式安装（bullmq 5 时代无需）。

````

## 使用

任务定义不变（主包文件约定 `src/tasks/<name>/task.ts`），只切驱动：

```ts
// faapi.config.ts
import type { FaapiConfig } from '@faapi/faapi';

export default {
  task: {
    driver: 'bullmq',
    bullmq: { connection: { host: '127.0.0.1', port: 6379 } },
    // 可选：同 Redis 下多应用隔离
    // bullmq: { connection: {...}, prefix: 'myapp' },
  },
} satisfies FaapiConfig;
````

```ts
// handler 里用法完全不变
export function POST(body, tasks) {
  return tasks.enqueue('send-email', { to: body.email });
}
```

## 语义映射

| faapi 驱动接口 | BullMQ |
| --- | --- |
| `enqueue(name, payload, { retries, delayMs, dedupId })` | `queue.add(name, payload, { attempts: retries + 1, backoff: exponential 500ms, delay, removeOnComplete, removeOnFail, jobId })`。终态任务默认 7 天后移除（`removeOnComplete`/`removeOnFail` 可覆盖，`false` 恢复永不清理）——BullMQ 默认永久保留终态任务，Redis 无界增长且 dedupId 去重在存活期内一直生效 |
| `startWorker(name, { concurrency, process })` | `new Worker(name, handler, { connection, concurrency, prefix })`；attempt 取 `job.attemptsStarted`（跨实例/重启准确） |
| `stop(timeoutMs)` | workers.close() + queues.close()（race 超时），超时 abort 在跑任务的 signal |
| `stopWorkers()` | 仅关 Worker（dev 热替换重注册用），Queue 连接保持 |
| `groups`（批量记账，语义见主包 taskBatch.md） | 两组 Redis key：`<prefix>:group:<id>`（批量行 hash：计数器 + 声明 + mode/nextIndex/payloads/carry）+ `<prefix>:group-members:<id>`（成员行 hash，jobId→'pending'/'p:'/'s:' 幂等守卫），常驻不自动清理；经 `defineCommand`/`runCommand`（BullMQ 类型化 Lua 扩展口，专用连接复用连接池不加新连接）原子计账（settle 同脚本推进 serial 激活指针并解码下一条 payload）。成员批量标识与序号以载荷包装随 data 存储（`{ __faapiGroup, __faapiGroupIndex, __faapiPayload }`，交付/查询还原）；`cancelRemaining` 仅对 waiting/delayed 成员 `job.remove()`，移除成功才落定；`settleRemaining` 按计数差值补齐落定 |
| 失败重试 | BullMQ 侧执行（attempts = retries + 1，指数退避 500ms 起） |

注意：BullMQ 不提供执行中任务的取消信号，但 `stop` 超时路径会 abort `taskCtx.signal`（任务监听 signal 可尽快退出）。

## License

MIT

## 常见问题

### @faapi/task-bullmq 是什么？

Redis上faapi - persistent队列的BullMQ任务队列驱动程序

### 如何安装 @faapi/task-bullmq？

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

### @faapi/task-bullmq 支持 TypeScript 吗？

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

### @faapi/task-bullmq 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @faapi/task-bullmq 需要什么版本的 Node\.js？

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

### @faapi/task-bullmq 可以商用吗？

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

### @faapi/task-bullmq 还在维护吗？

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