# @cloudflare/actors 中文文档

规范地址：https://npmcn.com/package/%40cloudflare/actors/

版本：0\.0\.1-beta\.6
npm 元数据更新时间：2026-09-03T14:17:42.009Z
中文译文更新时间：2026-11-10T02:52:20.600Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：226 kB，48 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：0 个
- 首次发布：2025-06-24T16:24:52.756Z
- 最新版本发布：2025-09-15T02:13:38.708Z
- 近 30 天下载量：31191（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 0 个）

## 中文简介

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

## 安装

```sh
npm install @cloudflare/actors
```

也可以使用：`pnpm add @cloudflare/actors`、`yarn add @cloudflare/actors`、`bun add @cloudflare/actors`

## README

# 云浮演员

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

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

## 特征

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

还有很多功能,看看 [实例](https://npmcn.com/package/%40cloudflare/actors/examples) 更多信息.

## 开始

### 步骤1:安装软件包

```bash
npm i @cloudflare/actors
```

### 第2步: 更新您的 Wrangler 配置

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

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

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

```typescript
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);
```

## 实例

-   [基本示例](https://npmcn.com/package/%40cloudflare/actors/examples/basic)
-   [请求处理器](https://npmcn.com/package/%40cloudflare/actors/examples/handler)
-   [RPC 接口](https://npmcn.com/package/%40cloudflare/actors/examples/rpc)
-   [管理实例](https://npmcn.com/package/%40cloudflare/actors/examples/manage-instances)
-   [生命周期钩](https://npmcn.com/package/%40cloudflare/actors/examples/lifecycle-hooks)
-   [地点](https://npmcn.com/package/%40cloudflare/actors/examples/location-placement)
-   [如何使用没有演员类](https://npmcn.com/package/%40cloudflare/actors/examples/durable-objects/)

## 财务问题

### 警报

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

冷启动 :

-   \[回
-   开始
-   提醒时

温暖开始 :

-   提醒时
-   \[回

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

### 常规

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

* * *

### 地点

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

* * *

见 [财务问题](https://npmcn.com/package/%40cloudflare/actors/FAQ.md) 对常见问题有更多的答案.

* * *

## 捐款

我们欢迎捐款! 请参看我们 [贡献准则](https://npmcn.com/package/%40cloudflare/actors/CONTRIBUTING.md) 更多信息.

## 许可证

这个项目根据麻省理工学院许可证颁发——见 [自由主义](https://npmcn.com/package/%40cloudflare/actors/LICENSE) 详细文件.

## 常见问题

### @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 和提交记录判断。