@cloudflare/actors

中文文档
0.0.1-beta.6发布于 2025/09/15MITTypeScriptES Module零依赖近 30 天下载 3.1万

用 Cloudflare 持久对象构建的更简单的方法

中文使用文档
文档目录12 节
  1. 特征
  2. 开始
  3. 步骤1:安装软件包
  4. 第2步: 更新您的 Wrangler 配置
  5. 步骤3: 创建您的类执行 :
  6. 实例
  7. 财务问题
  8. 警报
  9. 常规
  10. 地点
  11. 捐款
  12. 许可证

云浮演员

该项目正在积极发展之中.

我们正在建立一个全功能框架,通过引入新的模式和帮助开发者的框式功能,使开发Cloudflare 持久对象更加容易.

特征

  • 请求处理器 以方便定义您的演员、工人或请求的切入点
  • 生命周期方法 使您能够利用重要的生命周期事件
  • 持久性属性 将财产价值储存在要求和驱逐之间
  • RPC 接口 进入其他简单演员 MyActor.get('id') 接口
  • 管理实例 跟踪、删除并访问已创建的所有实例
  • 地点 允许您控制您的演员的位置
  • SQL 迁移 以应用迁移到 SQLite 存储
  • 多个提醒 以时间戳、 延迟或 cron 设置任何提醒数
  • 公用事业 用于使用带有焦急策略的指数回放重试操作,并检测持久对象错误是否可以重试.

还有很多功能,看看 实例 更多信息.

开始

步骤1:安装软件包

npm i @cloudflare/actors

第2步: 更新您的 Wrangler 配置

注意您 Typescript 执行中的代码类名必须匹配绑定 name, (中文(简体) ), class_name 财务报告和审定财务报表 new_sqlite_classes 配置中的值。 校验所有值匹配 .

{
  "migrations": [
    {
      "new_sqlite_classes": ["MyActor"],
      "tag": "v1"
    }
  ],
  "durable_objects": {
    "bindings": [
      {
        "class_name": "MyActor",
        "name": "MyActor"
      }
    ]
  }
}

步骤3: 创建您的类执行 :

import { Actor, handler } from "@cloudflare/actors";

export class MyActor extends Actor<Env> {
  async fetch(request: Request): Promise<Response> {
    return new Response("Hello, World!");
  }
}

export default handler(MyActor);

实例

财务问题

警报

警报触发器的生命周期是什么? 当一个演员被警报触发器震动时,它目前的行为顺序与演员已经被内存时的顺序略有不同. 下面是事件的顺序.

冷启动 :

  • [回
  • 开始
  • 提醒时

温暖开始 :

  • 提醒时
  • [回

对于温暖的开始, onInit 警报触发前就已经叫了.

常规

什么是演员? 演员是具有状态的可持久对象,既可以计算也可以存储。 您可以把它看作是一个小服务器实例, 当被访问和睡眠时是活跃的.
一个要求能让我的演员活多久? 单项请求会让演员活到~10秒.
我能让我的演员活得更久吗? 使用代码中的“定时通关”可以使其活到~60秒.
还有别的办法让我的密码能活得更久吗? 是的,你可以使用警报 让演员活着更长的时间.
每个新请求是否都重置时间直到演员不再被内存? 对.

地点

我如何控制我的演员的位置? 您可以使用位置提示来控制您的演员的位置 .
如果我不指定位置提示 我的演员住在哪里? 如果您未指定位置提示, 您的演员将被放置在最接近用户的区域 .
你能改变你的演员的位置或区域吗? 不,你不能改变你的演员的位置或区域。 一旦它被立即释放,它将永远生活在该地区。 如果您想要将您的演员移动到另一个区域, 您需要部署新版本的代码 .
用一个位置提示 我的演员将被放置在哪里? 如果有位置提示, 您的演员将被放置在指定区域 。 这个例子会在地点区域随机产生 你提供。 例如,如果你提供`enam ' 位置提示,这个实例将在北美东部地区随机产生.
如果我的演员所在的数据中心倒下怎么办? 如果您的演员所在的数据中心倒下, 您的演员将被移动到另一个数据中心 .

见 财务问题 对常见问题有更多的答案.


捐款

我们欢迎捐款! 请参看我们 贡献准则 更多信息.

许可证

这个项目根据麻省理工学院许可证颁发——见 自由主义 详细文件.

版本与发布记录

@cloudflare/actors 共发布 9 个版本,首次发布于 2025/06/25;过去 12 个月发布了 0 个版本。

版本发布日期距今
0.0.1-beta.6latest2025/09/151.2 年前
0.0.1-beta.52025/08/271.2 年前
0.0.1-beta.42025/08/211.2 年前
0.0.1-beta.32025/07/231.3 年前
0.0.1-beta.22025/07/221.3 年前
0.0.1-beta.12025/07/181.3 年前

关于 @cloudflare/actors 的常见问题

@cloudflare/actors 是什么?

用 Cloudflare 持久对象构建的更简单的方法

如何安装 @cloudflare/actors?

在项目目录运行 npm install @cloudflare/actors,或使用 pnpm add / yarn add / bun add。

@cloudflare/actors 支持 TypeScript 吗?

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

@cloudflare/actors 支持 ESM 还是 CommonJS?

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

@cloudflare/actors 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=18.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@cloudflare/actors 可以商用吗?

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

@cloudflare/actors 的下载量有多少?

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

@cloudflare/actors 还在维护吗?

最新版本 0.0.1-beta.6 发布于 2025/09/15(1.2 年前);至今共发布 9 个版本,其中过去 12 个月发布了 0 个;首次发布于 2025/06/25。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。