# @brust/cache-cloudflare 中文文档

规范地址：https://npmcn.com/package/%40brust/cache-cloudflare/

版本：2\.0\.0-alpha\.38
npm 元数据更新时间：2026-11-05T09:00:36.492Z
中文译文更新时间：2026-11-08T16:53:31.517Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：40.2 kB，15 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- peer 依赖：@brust/core 2\.0\.0-alpha\.38
- 首次发布：2026-10-12T14:42:25.000Z
- 最新版本发布：2026-11-05T09:00:36.274Z
- 近 30 天下载量：4460（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：37（近 12 个月 37 个）

## 中文简介

cloudflare工人的brust缓存适配器: KV 商店、持久对象广播/商店及其组合

## 安装

```sh
npm install @brust/cache-cloudflare
```

也可以使用：`pnpm add @brust/cache-cloudflare`、`yarn add @brust/cache-cloudflare`、`bun add @brust/cache-cloudflare`

## README

# @brust/cache-cloudflare (英语)

Cloudflare工人适配器用于Brust共享的第二缓存级(`[cache]` 内 `brust.toml`, (中文(简体) ), `brust build --target cloudflare`:

-   **`cloudflare-kv`**: 工人KV中的页面(一个商店,没有广播).
-   **`cloudflare-do`**: 通过持久对象(拉式广播)作废,也可以选用页面存储(`do_store = true`, 16 shards)) (中文(简体) ).
-   **`cloudflare-kv` + 键 `broadcast = "cloudflare-do"`**: 建议配对(`combine`KV 保存着尸体, 持久对象告诉每个隔离点什么是无效的 .

仅限工人(`runtimes: ['workers']`) (中文(简体) ). 没有 `bun`编号 :`bun:*` 导入。 同伴依赖 : `@brust/core`。 。 。 .

```toml
[cache]
adapter = "cloudflare-kv"
broadcast = "cloudflare-do"
epoch_interval_ms = 5000

[cache.cloudflare]
kv_min_ttl_s = 300
```

## Wrangler 绑定( 您声明它们; brust 从未添加它们)

`brust build --target cloudflare` 检查顶层和每个 `env.*` 块, 您的wrangler 配置, 当缺少一些东西时, 此片断失败 :

```jsonc
{
  "kv_namespaces": [{ "binding": "BRUST_CACHE", "id": "<wrangler kv namespace create brust-cache>" }],
  "durable_objects": { "bindings": [{ "name": "BRUST_CACHE_DO", "class_name": "BrustCacheDO" }] },
  "migrations": [{ "tag": "brust-cache-v1", "new_sqlite_classes": ["BrustCacheDO"] }]
}
```

`BrustCacheDO` 必须是 SQLite 支持的类( S) :`new_sqlite_classes`,或 `exports.BrustCacheDO = { "type": "durable-object", "storage": "sqlite" }`) (中文(简体) ). `brust build` 写入 `dist/cf/worker/main.js`,它会再出口;不要自己写.

## 选项( E)`[cache.cloudflare]`(中文(简体) )

| 键 | 用于 | 默认 | 规则 |
| --- | --- | --- | --- |
| `kv_binding` | KV, 对 | `"BRUST_CACHE"` | 在 `kv_namespaces` |
| `kv_min_ttl_s` | KV, 对 | `300` | `0..=31536000`;带有更小 ttl 的路由不写入 KV( KV 自己的地层为 60 s) |
| `do_binding` | 双 | `"BRUST_CACHE_DO"` | (单位:千美元) `durable_objects` 约束 `class_name "BrustCacheDO"` |
| `do_store` | 开始 | `false` | `true` = 16个可持久对象的躯体(与相对相混合) |

程序表(用于 `adapter = "custom"`: `kvAdapter({ binding?, min_ttl_s? })`, (中文(简体) ), `doAdapter({ binding?, store? })`, (中文(简体) ), `combine(kv, do)`。未知的密钥是 `TypeError` 点名.

## 每个配置保证

| 配置 | 存储 | 其他隔离 `cache.invalidate` | 腐烂的身体重新保养? | 免费计划费用驱动因素 |
| --- | --- | --- | --- | --- |
| `cloudflare-kv` 一个人 | 无人看守的 KV | 到 ttl (无广播) | **对**,最高为 ttl (至少300 s) | 每部写1 KV |
| `cloudflare-do`, (中文(简体) ), `do_store = false` | 无(仅第1级) | `epoch_interval_ms` +RTT 键 | 没有 | 每个隔离点每个民意测验1个DO请求 |
| `cloudflare-do`, (中文(简体) ), `do_store = true` | DO shards, 精确的写警卫 | `epoch_interval_ms` +RTT 键 | 否( 数被删除) | \+ 1 DO 请求每一级错报,+ 18 次无效 |
| `cloudflare-kv` + 键 `broadcast = "cloudflare-do"` | 木卫一 | `epoch_interval_ms` +RTT 键 | kV 时滞被每个条目隐藏 `entryStamp` | 每个MISS + DO 民调 |

**单凭KV永远不会失效.** L2密钥散列前缀,方法,路径和查询,所以没有额外的索引写入,KV中无法列出一个标记或路径. 与永久对象广播对等, 除非一个长达ttl的僵化页面是好的.

每对隔离都保留JS中的无效地层(在第一次接触时和一代人改变后从持久对象中引出),所以新开始的隔离从未为KV机体服务过,而KV机体在开始之前就已经失效了.

## 自由计划编号

| 驱动程序 | 每日费用 | 免费配额 | 说明 |
| --- | --- | --- | --- |
| 划时代的民意调查,一个忙于孤立, `epoch_interval_ms` 1 000个 | 86,400份DO请求 | 100 000份指定责任请求 | 86%用于隔离 |
| 5 000毫秒时相同 | 17 280个 | 10万个 | 大约5个忙于隔离 |
| 同为60 000毫秒 | 1 440个 | 10万个 | 约69个隔离区; 停滞约60 s |
| `do_store` 一级错失 | 1个DO 请求每个 | 10万个 | 加行读取 |
| 无效 | 1 DO 请求 (18 与 `do_store`\+ 最多写出5行 | 写出100 000行 |  |
| KV 写入 | 1 KV / MISS / ttl / 300 s 页 | 1000个字 | 对 Free 具有约束力的约束 |
| KV 读取 | 1 KV 每差一级读取 | 100 000读数 |  |

免费, 设置 `epoch_interval_ms >= 5000` 并选择 KV + DO 而不是 `do_store`A级 `do_store` 无效问题涉及动作引用中的18个子请求(自由允许50个);一个已经使超过30个的动作会看到硬性无效失败.

## 行为说明

-   持久目标继续 `seq` 及其SQLite存储器中的名至名层,因此以后的列表不会在重启时出现后退. 活动戒指在记忆中 `gen` 每个构件都是新的,所以每个隔离点在重启后会清理1级.
-   当此隔离器在60 s 以内写出相同的一页时, KV 写入被跳过( KV 允许每秒写一页) .
-   KV最终是一致的(多至60 s跨地点). 当地 `wrangler dev` KV具有很强的连贯性,因此测试套件没有覆盖传播滞后.

## 常见问题

### @brust/cache-cloudflare 是什么？

cloudflare工人的brust缓存适配器: KV 商店、持久对象广播/商店及其组合

### 如何安装 @brust/cache-cloudflare？

在项目目录运行 npm install @brust/cache-cloudflare，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@brust/core（2\.0\.0-alpha\.38）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @brust/cache-cloudflare 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/brust\_\_cache-cloudflare 是否存在。

### @brust/cache-cloudflare 支持 ESM 还是 CommonJS？

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

### @brust/cache-cloudflare 可以商用吗？

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

### @brust/cache-cloudflare 的下载量有多少？

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

### @brust/cache-cloudflare 还在维护吗？

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