# @durable-streams/server-cloudflare 中文文档

规范地址：https://npmcn.com/package/%40durable-streams/server-cloudflare/

版本：0\.1\.1
npm 元数据更新时间：2026-08-11T23:12:04.825Z
中文译文更新时间：2026-11-13T00:36:19.414Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：285 kB，16 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-08-11T23:12:04.119Z
- 最新版本发布：2026-08-11T23:12:04.471Z
- 近 30 天下载量：25176（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 1 个）

## 中文简介

Cloudflare Workers + 持久对象上的持久流协议服务器——导出流对象类,并在自己的工人中挂载处理器

## 安装

```sh
npm install @durable-streams/server-cloudflare
```

也可以使用：`pnpm add @durable-streams/server-cloudflare`、`yarn add @durable-streams/server-cloudflare`、`bun add @durable-streams/server-cloudflare`

## README

# @可持久流/服务器-云浮lare

符合者 [持久流](https://github.com/durable-streams/durable-streams) 协议服务器启用 **云花板工人+持久性物体**,在 TypeScript 中——您在自己的“工作员”中挂载的库.

每个流都是它自己的持久对象实例(`idFromName(streamPath)`),通过DO输入/输出门免费给出协议的每流序列化和耐久性. 所有状态都活在 DO SQLite;长波服务员和SSE 尾巴在对象中被持有;滑动的 TTL 使用 DO 提醒;分叉语义(被重新计算出软-去除,被缝合的读取,级联GC)通过 DO-到 DO RPC 在对象之间工作.

## 使用量

```bash
pnpm add @durable-streams/server-cloudflare   # or npm install / yarn add
```

您的工人条目 :

```ts
// src/index.ts
import { createStreamsHandler } from "@durable-streams/server-cloudflare"

export { StreamObject } from "@durable-streams/server-cloudflare"

export default {
  fetch: createStreamsHandler(),
}
```

您的wrangler配置 — DO 绑定 **必须是命名 `STREAMS`** (fork semics do-to-DO RPC通过它)并且需要SQLite迁移:

```jsonc
// wrangler.jsonc
{
  "name": "my-streams",
  "main": "src/index.ts",
  "compatibility_date": "2025-06-01",
  "durable_objects": {
    "bindings": [{ "name": "STREAMS", "class_name": "StreamObject" }],
  },
  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["StreamObject"] }],
}
```

图书馆类型 参考 工人运行时间类型(`DurableObjectNamespace`——在您的项目中以 [`wrangler types`](https://developers.cloudflare.com/workers/languages/typescript/#generate-types)。 。 。 .

溪流居住于 `/<path>` ——完整请求路径名为流路径. 如果您将处理器挂载在更大的工作人体内,则只路径流 URL 到它(各流之间的叉引用使用这些路径,所以保持它们的稳定) 。 见 [`chat-cloudflare` 实例](https://npmcn.com/package/examples/chat-cloudflare) 一个TanStack Start的应用程序 和这个服务器共享一个工作人.

### 认证

议定书赋予执行权。 默认情况下,如果 `AUTH_TOKEN` var/secret 设置和不空, 每一份请求必须携带 `Authorization: Bearer <token>` (单位:千美元)`npx wrangler secret put AUTH_TOKEN`; 否则服务器已经打开 。 通过自己的钩子来取而代之——返回 a `Response` 要拒绝的, `undefined` 允许:

```ts
export default {
  fetch: createStreamsHandler({
    auth: async (request, env) => {
      if (!(await isAuthorized(request, env))) {
        return new Response("Unauthorized", { status: 401 })
      }
      return undefined
    },
  }),
}
```

`createStreamsHandler({ cors: false })` 省略允许默认的 CORS 头.

## 遵约

经验证 `@durable-streams/server-conformance-tests` 整个套间,包括叉子语义和自制围栏: **326通过,0失败** (与参考服务器相同;6个跳出是套房自己的) `subscriptions`\- 网钩测试,默认关闭 - 实验 `__ds` 未执行订阅控制平面并返回 `404`) (中文(简体) ).

```bash
pnpm conformance   # boots template/index.ts via wrangler dev (test/wrangler.jsonc) and runs the suite
```

## 版式

| 路径 | 这是什么 |
| --- | --- |
| `src/index.ts` | 库条目:导出 `StreamObject`, (中文(简体) ), `createStreamsHandler`,类型 |
| `src/handler.ts` | 工人路由器厂:路由线、CORS预飞、认证钩 |
| `src/stream-object.ts` | `StreamObject` Do:所有协议语义(PUT/GET/POST/DELETE/HEAD,长波,SSE,出品人,关闭,TTL,叉) |
| `src/store.ts` | SQLite 访问层 (`meta` 编号 : `messages` 编号 : `producers` 页:1 |
| `src/producer.ts` | 纯一能-出产国验证机 |
| `src/json.ts` | JSON 模式帮助器( 阵列平整、 碎片存储、 阵列包装读取) |
| `src/cursor.ts` | CDN 缓存折叠光标数学 |
| `template/index.ts` | 工人输入符合性测试靴(上面的用法片段,完整) |
| `test/` | 遵守规则:靴子 `wrangler dev` 运行共享套房 |

## 开发

```bash
pnpm build       # emit dist/ (library build)
pnpm conformance # full conformance suite against a local wrangler dev instance
pnpm typecheck
```

线程和格式化来自 repo 根(`pnpm lint`, (中文(简体) ), `pnpm format` 在单发根.

## 设计说明

-   **减值** 使用参考格式 `<readSeq>_<byteOffset>` (16位零加法,可按词法排序);每封信推进字节由 `payload + 5` (frame haybook),匹配参考服务器字节换字节.
-   **货币**:请求体在任何状态被检查之前都会被读取;每个验证-当时-写入块在SQLite API上是同步的,所以DO事件循环使它成为原子——不需要锁.
-   **TTL 电话** 在访问时懒惰地执行(准确) _财务报告和审定财务报表_ 以 DO 提醒( 仓库回收) , 因此 1秒 TTL 即时失效 .
-   **车身盖** 每个附件为~1.9MB(DO SQLite的2MB值限制);较大的附件获得协议 `413`。 。 。 .
-   **叉子**: 创建分叉解析法验证 + 重新计算来源的 DO(`forkAcquire`);删除一个引用的流软删除它(`410 Gone`),最后一叉放出会连结到链条上硬地清洗.

## 许可证

[阿帕奇 - 2.0](https://npmcn.com/package/%40durable-streams/server-cloudflare/LICENSE)。协议/验证逻辑从 Apache-2.0 移植 [参考服务器](https://github.com/durable-streams/durable-streams/tree/main/packages/server) (可转让流捐助者)——见 [通知](https://npmcn.com/package/%40durable-streams/server-cloudflare/NOTICE) 和每个文件的归属标题.

## 常见问题

### @durable-streams/server-cloudflare 是什么？

Cloudflare Workers \+ 持久对象上的持久流协议服务器——导出流对象类,并在自己的工人中挂载处理器

### 如何安装 @durable-streams/server-cloudflare？

在项目目录运行 npm install @durable-streams/server-cloudflare，或使用 pnpm add / yarn add / bun add。

### @durable-streams/server-cloudflare 支持 TypeScript 吗？

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

### @durable-streams/server-cloudflare 支持 ESM 还是 CommonJS？

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

### @durable-streams/server-cloudflare 可以商用吗？

@durable-streams/server-cloudflare 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @durable-streams/server-cloudflare 的下载量有多少？

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

### @durable-streams/server-cloudflare 还在维护吗？

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