# @better-bull-board/client 中文文档

规范地址：https://npmcn.com/package/%40better-bull-board/client/

版本：0\.2\.1
npm 元数据更新时间：2026-10-30T18:22:29.005Z
中文译文更新时间：2026-11-07T23:58:03.173Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%40better-bull-board/client
原文对照：https://npmcn.com/package/%40better-bull-board/client/?lang=original
项目主页：https://github.com/dimension-studios-inc/better-bull-board#readme
源码仓库：https://github.com/dimension-studios-inc/better-bull-board

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

- 包体积（解压后）：37 kB，46 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：bullmq ^6\.0\.0
- 首次发布：2025-09-29T10:13:38.307Z
- 最新版本发布：2026-10-30T18:22:28.672Z
- 近 30 天下载量：5088（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：27（近 12 个月 12 个）

## 中文简介

开发者将Better Bulk Board 与您的 BullMQ 工人整合的文件 .

## 安装

```sh
npm install @better-bull-board/client
```

也可以使用：`pnpm add @better-bull-board/client`、`yarn add @better-bull-board/client`、`bun add @better-bull-board/client`

## README

# @ better-bull-board/客户端

开发者将Better Bulk Board 与您的 BullMQ 工人整合的文件 .

## 安装

```bash
pnpm add @better-bull-board/client bullmq
```

`bullmq` 属于对等关系( e)`^6`) (中文(简体) ). 安装您的应用程序使用的版本; 它不需要匹配此软件包的针 .

## 使用量

要使用更好的公牛板 与你的公牛MQ工人, 你需要:

1.  **导入 BBB 客户端**
2.  **使用单独的处理器** (取消职务所需的散装箱处理器)

### 基本设置

#### 1\. 创建处理器文件

创建一个单独的处理器文件(例如, `processor.ts` 或者说 `processor.js`:

```typescript
import { patch } from "@better-bull-board/client"
import type { SandboxedJob } from "bullmq"

import { redis } from "./lib/redis" // Your Redis connection

export default patch(async (job: SandboxedJob) => {
  console.log(`Processing job ${job.id}`)

  // Your job processing logic here
  await processYourJob(job.data)

  console.log(`Job ${job.id} completed`)

  return { status: "done" }
}, redis)
```

#### 2\. 创建工人

使用您主文档中更好的公牛板工人班:

```typescript
import path from "node:path"

import { Worker } from "@better-bull-board/client"

import { redis } from "./lib/redis" // Your Redis connection

const processorFile = path.join(__dirname, "processor.cjs") // Note: .cjs extension for built files

new Worker("your-queue-name", processorFile, {
  connection: redis,
  ioredis: redis,
  useWorkerThreads: true,
  concurrency: 10,
  getJobTags(job) {
    // Optional: Return tags for better organization
    return ["your-queue", "production"]
  },
})
```

### 关键要求

-   **单独的处理器**: 您必须使用沙盒处理器( 分离文件) 才能正常工作
-   **Redis 连接**: 提供两者 `connection` 财务报告和审定财务报表 `ioredis` 选项指向相同的 Redis 实例
-   **工人线索**设置 `useWorkerThreads: true` 适当隔离
-   **文件扩展名**: 使用 `.cjs` 引用已建文件时处理器文件路径的扩展名

### 完整示例

这里有一个完整的工作例子 依据我们的演示:

**处理器.ts**

```typescript
import { patch } from "@better-bull-board/client"
import type { SandboxedJob } from "bullmq"

import { redis } from "../lib/redis"

export default patch(async (job: SandboxedJob) => {
  console.log(`Processing job ${job.id}`)

  // Simulate work
  await new Promise((resolve) => setTimeout(resolve, 10_000))

  console.log(`Job ${job.id} processed`)

  return { status: "done" }
}, redis)
```

**工 作 员**

```typescript
import path from "node:path"
import { fileURLToPath } from "node:url"

import { Worker } from "@better-bull-board/client"

import { redis } from "./lib/redis"

const __filename = fileURLToPath(import.meta.url)
const __dirname = path.dirname(__filename)
const processorFile = path.join(__dirname, "processor.cjs")

new Worker("demo-queue", processorFile, {
  connection: redis,
  ioredis: redis,
  useWorkerThreads: true,
  concurrency: 10,
  getJobTags() {
    return ["demo-queue", "test"]
  },
})
```

### 高级特性

#### 任务取消

这个 `patch` 函数提供内置任务取消支持。 工作可以通过Better Bulk Board UI取消.

#### 工作日志

处理器的所有控制台输出都会自动被捕获并被送到Better Bull Board进行监控.

直接写出字的伐木工,比如 [皮诺](https://getpino.io/)绕行 `console`。给 Pino 工作日志目标,所以每行也到达当前任务 :

```typescript
import { createPinoJobLogDestination } from "@better-bull-board/client"
import { pino } from "pino"

export const logger = pino(
  { level: "info" },
  pino.multistream([
    { stream: process.stdout, level: "trace" },
    { stream: createPinoJobLogDestination({ ignore: ["trace_id"] }), level: "trace" },
  ]),
)
```

目的地保留 `msg`,将其他字段作为 JSON 和打印 `err` 犹如被抛弃的迷误一样`code`, (中文(简体) ), `data`(......) ; (......); `ignore` 在工作日志中丢弃您不想要的密钥( r)`pid` 财务报告和审定财务报表 `hostname` 已经是). 在工作之外,它是一个不开放的,所以一个日志实例既服务于工人,也服务于它的处理器.

任何其他日志可以调用 `relayJobLog({ level, message })` 从它的运输:它将线导到任务上,绑定在当前的同步上下文中,而别无他法.

#### 任务标记

使用 `getJobTags` 在更好的公牛板界面中组织和过滤您的工作的函数:

```typescript
getJobTags(job) {
  return [
    job.queueName,
    job.data.priority || "normal",
    process.env.NODE_ENV || "development"
  ];
}
```

## API 参考

### `patch(processor, redis)`

用更好的公牛板功能包扎工作处理器.

-   `processor`: 您的同步工作处理功能
-   `redis`: Redis 连接实例

### `createPinoJobLogDestination(options?)`

一个将每个日志行转发到当前工作日志的皮诺目的地.

-   `options.ignore`: 从中继消息中丢出的额外密钥

### `relayJobLog({ level, message })`

将一个日志行转发到绑定在当前同步上下文(如果有的话)的工作. `level` 这是其中之一 `log`, (中文(简体) ), `debug`, (中文(简体) ), `info`, (中文(简体) ), `warn`, (中文(简体) ), `error`。 。 。 .

### `Worker`

延伸公牛MQ Worker 与更好的公牛板整合.

**所需的选项 :**

-   `ioredis`: Redis 连接实例
-   `useWorkerThreads`: 必须是 `true`
-   `getJobTags`: 可选函数返回工作标签

## 解决问题

-   **无法工作的工作取消**: 确保您使用沙盒处理器( 分离文件)
-   **未出现的工作**: 检查您的 Redis 连接是否配置得当
-   **建立问题**: 确保参考 `.cjs` 用于已建处理器的文件

## 常见问题

### @better-bull-board/client 是什么？

开发者将Better Bulk Board 与您的 BullMQ 工人整合的文件 \.

### 如何安装 @better-bull-board/client？

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

### @better-bull-board/client 支持 TypeScript 吗？

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

### @better-bull-board/client 支持 ESM 还是 CommonJS？

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

### @better-bull-board/client 可以商用吗？

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

### @better-bull-board/client 的下载量有多少？

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

### @better-bull-board/client 还在维护吗？

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