# @fedify/cfworkers 中文文档

规范地址：https://npmcn.com/package/%40fedify/cfworkers/

版本：2\.1\.32
npm 元数据更新时间：2026-11-17T06:43:45.771Z
中文译文更新时间：2026-11-17T06:01:39.112Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：22.5 kB，5 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@fedify/fedify ^2\.1\.32，@cloudflare/workers-types ^4\.20250906\.0 \|\| ^5\.0\.0
- 首次发布：2025-08-26T07:03:34.690Z
- 最新版本发布：2026-11-17T06:43:45.419Z
- 近 30 天下载量：9469（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：757（近 12 个月 626 个）

## 中文简介

与云花板工人联合

## 安装

```sh
npm install @fedify/cfworkers
```

也可以使用：`pnpm add @fedify/cfworkers`、`yarn add @fedify/cfworkers`、`bun add @fedify/cfworkers`

## README

# @feedify/cfworks:适应与云浮工人的结合

[![JSR](https://jsr.io/badges/@fedify/cfworkers)](https://jsr.io/@fedify/cfworkers) [![npm](https://img.shields.io/npm/v/@fedify/cfworkers?logo=npm)](https://www.npmjs.com/package/@fedify/cfworkers) [![Follow @fedify@hollo.social](https://fedi-badge.deno.dev/@fedify@hollo.social/followers.svg)](https://hollo.social/@fedify)

_该包自1.9.0联邦化后即可提供._

此软件包提供 [联邦](https://fedify.dev/)是因为 [`KvStore`](https://jsr.io/@fedify/fedify/doc/federation/~/KvStore) 财务报告和审定财务报表 [`MessageQueue`](https://jsr.io/@fedify/fedify/doc/federation/~/MessageQueue) 执行 [云花岗工人](https://workers.cloudflare.com/)数字 :

-   [`WorkersKvStore`](https://jsr.io/@fedify/cfworkers/doc/~/WorkersKvStore)
-   [`WorkersMessageQueue`](https://jsr.io/@fedify/cfworkers/doc/~/WorkersMessageQueue)

```typescript
import { createFederation, type Message } from "@fedify/fedify";
import { WorkersKvStore, WorkersMessageQueue } from "@fedify/cfworkers";

type Env = {
  KV_BINDING: KVNamespace<string>;
  QUEUE_BINDING: Queue;
};

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const federation = createFederation<Env>({
      kv: new WorkersKvStore(env.KV_BINDING),
      queue: new WorkersMessageQueue(env.QUEUE_BINDING),
      // Cloudflare Queues cannot be polled, so the queue() handler below
      // consumes the messages instead of Federation.startQueue():
      manuallyStartQueue: true,
      // ... other options
    });

    return await federation.fetch(request, { contextData: env });
  },

  async queue(batch: MessageBatch<unknown>, env: Env): Promise<void> {
    const federation = createFederation<Env>({
      kv: new WorkersKvStore(env.KV_BINDING),
      queue: new WorkersMessageQueue(env.QUEUE_BINDING),
      // Inbox listeners run inside processQueuedTask() and may call
      // ctx.sendActivity(), which would otherwise start the queue workers
      // automatically:
      manuallyStartQueue: true,
      // ... other options
    });

    for (const message of batch.messages) {
      await federation.processQueuedTask(env, message.body as Message);
    }
  },
} satisfies ExportedHandler<Env>;
```

## `WorkersKvStore`

`WorkersKvStore` 关键值存储执行 [云花岗工人](https://workers.cloudflare.com/) 使用 Cloudflare 的内置 [云花板工人 KV](https://developers.cloudflare.com/kv/) API (英语). 它规定 cloudflare工人环境的持续储存和良好业绩. 适合用于Cloudflare工人应用的生产.

## `WorkersMessageQueue`

`WorkersMessageQueue` 是信件队列执行 [云花岗工人](https://workers.cloudflare.com/) 使用 Cloudflare 的内置 [云浮队列](https://developers.cloudflare.com/queues/) API (英语). 它规定 可伸缩性和高性能,使其适合用于生产 云浮工人环境. 它需要一个 Cloudflare 队列设置和 管理层.

> \[注\] 自从你 `KVNamespace` 财务报告和审定财务报表 `Queue` 不受全球变量的约束,但 而不是作为论据提交 `fetch()` 财务报告和审定财务报表 `queue()` 方法,你需要 {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}来洗涤你的 `Federation` 这些方法中的对象,而不是 顶级.
> 
> 为了更好的组织,你可能想要使用一个构建者模式 在即时播放前,登记您的调度员和听众 `Federation` 对象.

> \[注\] 这个 [云浮队列](https://developers.cloudflare.com/queues/) API 无法对来自 队列,所以 `WorkersMessageQueue.listen()` 方法总是抛出 (单位:千美元) `TypeError` 当被引用时。 相反,你应该定义一个 `queue()` 方法 在你的云花板工人, 将被云花板队称为 当队列中出现新消息时 API 。 内部 `queue()` 方法,需要调用 `Federation.processQueuedTask()` 手动方法 处理信件。 这个 `queue()` 方法是唯一的消费方式 来自 Cloudflare Workers 队列的消息。 设定 `manuallyStartQueue` 改为 `true` 也一样;否则,联邦将自动启动工人, 并自 `listen()` 扔出,它记录了无法启动的警告.

## 安装

```sh
deno add jsr:@fedify/cfworkers  # Deno
npm  add     @fedify/cfworkers  # npm
pnpm add     @fedify/cfworkers  # pnpm
yarn add     @fedify/cfworkers  # Yarn
bun  add     @fedify/cfworkers  # Bun
```

## 常见问题

### @fedify/cfworkers 是什么？

与云花板工人联合

### 如何安装 @fedify/cfworkers？

在项目目录运行 npm install @fedify/cfworkers，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@fedify/fedify（^2\.1\.32）、@cloudflare/workers-types（^4\.20250906\.0 \|\| ^5\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @fedify/cfworkers 支持 TypeScript 吗？

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

### @fedify/cfworkers 支持 ESM 还是 CommonJS？

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

### @fedify/cfworkers 可以商用吗？

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

### @fedify/cfworkers 的下载量有多少？

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

### @fedify/cfworkers 还在维护吗？

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

