BullMQ 初学者教程

本教程基于 BullMQ 官方文档 编写，面向第一次在 Node.js、TypeScript 项目中使用后台任务队列的开发者。

BullMQ 是建立在 Redis 之上的任务队列库。它把“提交任务”和“执行任务”分开，使 Web 服务不必在一次 HTTP 请求中完成邮件发送、报表生成、图片处理等耗时工作。

本教程的项目约定

当前项目使用 TypeScript 编写源码，代码中使用 import / export，再由 tsconfig.json 将模块转换成 CommonJS：

{
  "compilerOptions": {
    "module": "commonjs"
  }
}

因此示例统一采用：

import { Queue, Worker } from "bullmq";

运行示例时仍可使用：

ts-node producer.ts
ts-node worker.ts

这不要求项目切换到原生 ESM。

学习路线

  1. 为什么需要 BullMQ
  2. 安装与快速开始
  3. Redis 连接管理
  4. Queue 与任务生产者
  5. Job 数据、ID 与去重
  6. Worker 与并发
  7. 失败、重试与 Stalled Job
  8. 延迟、优先级与 LIFO
  9. Job Schedulers 定时任务
  10. 队列限流
  11. 事件、进度与任务结果
  12. Flows 与任务依赖
  13. Sandboxed Processor、取消与超时
  14. 批量添加与吞吐量优化
  15. 幂等性与任务设计
  16. 指标、事件与遥测
  17. 生产部署与故障排查
  18. Express 与 Worker 项目实战

建议学习顺序

BullMQ 的四个核心类

官方 Introduction 首先介绍四个核心类：

类 主要职责
Queue 添加任务、查询和管理队列
Worker 获取并执行任务
QueueEvents 在独立进程中监听队列级事件
FlowProducer 创建有父子依赖的任务树

不要一开始就使用全部功能。第一个示例只需要 Queue 和 Worker。

版本说明

教程以当前 BullMQ 官方文档中的现代 API 为准，尤其使用 Job Schedulers，而不是旧教程中常见的 Repeatable Jobs 管理方式。

开始项目时记录实际版本：

npm list bullmq

升级大版本前阅读：

官方资料