# @di-framework/cloudflare 中文文档

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

版本：6\.0\.30
npm 元数据更新时间：2026-11-06T22:53:07.633Z
中文译文更新时间：2026-11-12T06:28:05.891Z
软件包许可：\(MIT OR Apache-2\.0\)

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

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

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

- 包体积（解压后）：64.5 kB，24 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：typescript ^5 \|\| ^6 \|\| ^7，@di-framework/core ^6
- 首次发布：2026-10-06T00:29:29.131Z
- 最新版本发布：2026-11-06T22:53:07.127Z
- 近 30 天下载量：3618（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 26 个）

## 中文简介

Cloudflare 工人连接器,用于绑定发现,wrangler config,以及自动化的DI注射.

## 安装

```sh
npm install @di-framework/cloudflare
```

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

## README

# @di-framework/ cloudflare (日语)

云花板工人连接器 `@di-framework`它将工人绑定物分类,阅读wrangler声明,并通过DI容器注入.

工人的捆绑物按要求运抵 `env` 对象。 启动时登记工厂,然后公布 `env` 在解析服务前从处理器中获取.

## 特征

-   **运行时间检测**数字 : `CloudflareDetector` 匹配工人用户代理和 `CF_PAGES=1`。 。 。 .
-   **具有约束力的分类** kV, D1, R2, 持久对象命名空间, 队列, 服务绑定, 工人AI, Hyperdrive, Vectorize, Analytics engine, Images, Workflows, 速率限制, 浏览器, 管道, 以及平面 vars.
-   **怀格勒宣言** 对于主机对象看起来相似的种类:资产、电子邮件、发送命名空间、秘密存储和mTLS证书。 还有 `vars`。 。 。 .
-   **DI 整合**数字 :
    -   `@CloudflareBinding('BINDING_NAME')` 参数和财产注入
    -   `@EnableCloudflareBindings()` 用于整个集装箱的懒惰工厂
    -   `setCloudflareBindings(env)` 从工人处理器
-   **本地倒计时**数字 : `CLOUDFLARE_BINDINGS` JSON, 或一个物体通过为 `localFallback`,当没有发布工人信息.
-   **自定义分类器** 结束 `BindingClassifierRegistry`。 。 。 .

## 安装

```bash
bun add @di-framework/cloudflare
```

## 快开始

```typescript
import { Container } from '@di-framework/core/decorators';
import {
  CloudflareBinding,
  type D1BindingInfo,
  EnableCloudflareBindings,
  type KvBindingInfo,
  setCloudflareBindings,
} from '@di-framework/cloudflare';

@EnableCloudflareBindings()
@Container()
export class OrderService {
  @CloudflareBinding('ORDERS')
  db!: D1BindingInfo;

  @CloudflareBinding('SESSIONS')
  sessions!: KvBindingInfo;

  async cart(id: string) {
    return this.sessions.binding?.get(id);
  }
}

export default {
  async fetch(request: Request, env: Record<string, unknown>) {
    setCloudflareBindings(env);
    const orders = new OrderService();
    const cart = await orders.cart(new URL(request.url).pathname);
    return new Response(cart == null ? 'empty' : String(cart));
  },
};
```

打电话 `setCloudflareBindings(env)` 在第一次读取注入属性之前。 财产获得者保留他们解决的第一个值.

## 程序发现

```typescript
import { CloudflareEnvironment } from '@di-framework/cloudflare';

const cf = new CloudflareEnvironment({ bindings: env });

const db = cf.getD1Binding('ORDERS');
const sessions = cf.getKvBinding('SESSIONS');
const bucket = cf.getR2Binding();
```

`getKvBinding()` 没有名称返回第一个 KV 按名称顺序绑定 。 D1, R2, 持久对象, 队列, 服务绑定, AI, Hyperdrive, Vectorize, 以及 Analytics engine也存在相同的模式 .

## 使用方式 `@di-framework/ai`

`WorkersAiChatModel` 财务报告和审定财务报表 `WorkersAiEmbeddingModel` 带工人AI捆绑. `VectorizeVectorStore` 以矢量约束。 一个函数读取 env 所发表的内存 `setCloudflareBindings`。 。 。 .

```typescript
import { configureAi, VectorizeVectorStore, WorkersAiChatModel, WorkersAiEmbeddingModel } from '@di-framework/ai';
import { getCloudflareBindings, setCloudflareBindings } from '@di-framework/cloudflare';

configureAi({
  chatModel: new WorkersAiChatModel({
    binding: () => getCloudflareBindings()?.AI,
    model: '@cf/meta/llama-3.1-8b-instruct',
  }),
});

export default {
  fetch(request: Request, env: Record<string, unknown>) {
    setCloudflareBindings(env);
    const embeddings = WorkersAiEmbeddingModel.of(() => env.AI);
    const store = new VectorizeVectorStore({
      index: () => env.VECTORS,
      embeddingModel: embeddings,
    });
    return new Response(String(store.name));
  },
};
```

`@CloudflareBinding('AI')` 注射数 `{ binding }`,这两个模型直接接受.

弦束为 var. 列于 `secretNames` 这是秘密. `kindHints` 当活的物体模糊时,强迫一种物体:

```typescript
new CloudflareEnvironment({
  bindings: env,
  secretNames: ['API_TOKEN'],
  kindHints: { ASSETS: 'assets', SECRETS: 'secrets-store' },
});
```

一种解析的wrangler配置(JSON,不是JSONC)也提供这些种类. `parseWranglerBindings(config)` 读取 `kv_namespaces`, (中文(简体) ), `d1_databases`, (中文(简体) ), `r2_buckets`, (中文(简体) ), `durable_objects`,队列制作人, `services`, (中文(简体) ), `ai`, (中文(简体) ), `hyperdrive`, (中文(简体) ), `vectorize`, (中文(简体) ), `analytics_engine_datasets`, (中文(简体) ), `ratelimits`, (中文(简体) ), `workflows`, (中文(简体) ), `send_email`, (中文(简体) ), `pipelines`, (中文(简体) ), `dispatch_namespaces`, (中文(简体) ), `secrets_store_secrets`, (中文(简体) ), `mtls_certificates`, (中文(简体) ), `browser`, (中文(简体) ), `images`, (中文(简体) ), `assets`,以及 `vars`。 。 。 .

外部工人,一个 JSON 对象在 `CLOUDFLARE_BINDINGS` 填入同一张地图。 设定 `localFallback: false` 要求已公布的“工人环境”.

## 自定义分类器

```typescript
import {
  type CloudflareBindingClassifier,
  getDefaultRegistry,
  type CloudflareBindingInfo,
} from '@di-framework/cloudflare';

class FlagClassifier implements CloudflareBindingClassifier {
  readonly kind = 'unknown' as const;

  accept(_name: string, value: unknown): boolean {
    return typeof value === 'object' && value !== null && 'flag' in value;
  }

  create(name: string, value: unknown): CloudflareBindingInfo {
    return { name, kind: 'unknown', binding: value };
  }
}

getDefaultRegistry().register(new FlagClassifier());
```

默认优先级是 `high`,所以分类器运行在内置之前. `{ priority: 'low' }` 跟着他们.

## 许可证

任何许可 [麻省理工学院](https://npmcn.com/package/LICENSE-MIT) 或者说 [阿帕奇 - 2.0](https://npmcn.com/package/LICENSE-APACHE)随便你.

## 常见问题

### @di-framework/cloudflare 是什么？

Cloudflare 工人连接器,用于绑定发现,wrangler config,以及自动化的DI注射\.

### 如何安装 @di-framework/cloudflare？

在项目目录运行 npm install @di-framework/cloudflare，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：typescript（^5 \|\| ^6 \|\| ^7）、@di-framework/core（^6）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @di-framework/cloudflare 支持 TypeScript 吗？

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

### @di-framework/cloudflare 支持 ESM 还是 CommonJS？

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

### @di-framework/cloudflare 可以商用吗？

@di-framework/cloudflare 使用 \(MIT OR Apache-2\.0\) 许可。可在 MIT、Apache-2\.0 中任选其一遵守。选择 MIT 时，宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @di-framework/cloudflare 的下载量有多少？

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

### @di-framework/cloudflare 还在维护吗？

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