# @computesdk/cloudflare 中文文档

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

版本：2\.1\.12
npm 元数据更新时间：2026-11-06T13:39:48.132Z
中文译文更新时间：2026-11-10T14:23:38.756Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：170 kB，10 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2025-09-13T02:09:44.493Z
- 最新版本发布：2026-11-06T13:39:47.605Z
- 近 30 天下载量：12920（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：92（近 12 个月 86 个）

## 中文简介

Cloudflare 计算SDK 提供商 - 使用 Cloudflare 工人和持久对象执行边码

## 安装

```sh
npm install @computesdk/cloudflare
```

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

## README

# @ computesdk/ cloudflare (英语)

Cloudflare ComputeSDK的提供商——在Cloudflare的边缘网络上以安全,孤立的容器执行代码.

## 安装

```bash
npm install @computesdk/cloudflare
```

## 设置

调出桥工 [`worker/`](https://npmcn.com/package/%40computesdk/cloudflare/worker)它需要一个关于工人付费计划的Cloudflare账户和Docker在当地运行; `wrangler deploy` 建立容器图像并把它们推向Cloudflare的注册.

```bash
git clone https://github.com/computesdk/computesdk.git
cd computesdk/packages/cloudflare/worker
npm ci
npx wrangler login
openssl rand -hex 32   # use the output as the API key
npx wrangler secret put SANDBOX_API_KEY
npx wrangler deploy
```

然后配置您的应用程序 :

```bash
CLOUDFLARE_SANDBOX_URL=https://computesdk-sandbox.<your-subdomain>.workers.dev
CLOUDFLARE_SANDBOX_API_KEY=<same value as SANDBOX_API_KEY>
```

您也可以运行 :

```bash
npx @computesdk/cloudflare
```

打印这些设置指令.

调来一名工人 [云花板沙盒演示](https://github.com/cloudflare/containers-demos/tree/main/sandbox) 继续为命令和文件工作。 适配器检查 `GET /v1/info` 并仅在工人列出时使用桥的本地文件传输,预览 URL和快照.

### 预览 URL

和桥工人, `sandbox.getUrl({ port })` 返回时 `<sandboxUrl>/v1/sandbox/<id>/ports/<port>/`,将 HTTP 和 WebSocket 请求转发到该端口。 服务器必须收听 `0.0.0.0`预览 URL 不需要 API 键: 任何拥有 URL 的人都可以到达端口.

### 抓图

和桥工人, `compute.snapshot.create(sandboxId)` 保存沙盒的文件系统并 `compute.instances.create({ snapshotId })` 从它开始一个新的沙盒。 快照只保存文件,而不是内存或运行过程. Cloudflare 将快照数据保存在创建或最后一次恢复后30天; `snapshot.delete` 从桥上取出手柄.

## 快速启动

```typescript
import { cloudflare } from '@computesdk/cloudflare';

const compute = cloudflare({
  sandboxUrl: process.env.CLOUDFLARE_SANDBOX_URL,
  sandboxApiKey: process.env.CLOUDFLARE_SANDBOX_API_KEY,
});

const sandbox = await compute.instances.create();

const result = await sandbox.runCommand(
  "node -e 'console.log(\"Hello from Cloudflare!\")'"
);

console.log(result.stdout);
await sandbox.destroy();
```

## 使用量

### 运行命令

在沙盒内使用普通 shell 命令 :

```typescript
await sandbox.runCommand('echo "Hello from Cloudflare"');
await sandbox.runCommand("node -e 'console.log(\"Hello Node.js\")'");
```

### 列表文件

```typescript
const result = await sandbox.runCommand('ls -la /tmp/app');
console.log(result.stdout);
```

### 文件系统

```typescript
// Create directories
await sandbox.filesystem.mkdir('/tmp/app/data');

// Write and read files
await sandbox.filesystem.writeFile('/tmp/app/config.json', JSON.stringify({ key: 'value' }));
const content = await sandbox.filesystem.readFile('/tmp/app/config.json');

// List directory contents
const files = await sandbox.filesystem.readdir('/tmp/app');

// Check existence
const exists = await sandbox.filesystem.exists('/tmp/app/config.json');

// Remove files
await sandbox.filesystem.remove('/tmp/app/temp.txt');
```

### 环境变量

初始化时将环境变量传递到沙盒命令 :

```typescript
const compute = cloudflare({
  sandboxUrl: process.env.CLOUDFLARE_SANDBOX_URL,
  sandboxApiKey: process.env.CLOUDFLARE_SANDBOX_API_KEY,
  envVars: {
    API_KEY: 'your-api-key',
    DATABASE_URL: 'postgresql://localhost:5432/mydb',
  },
});
```

或创建时的每盒:

```typescript
const sandbox = await compute.instances.create({
  envs: { NODE_ENV: 'production' },
});
```

### 沙盒大小和图像

创建时选择新沙盒的大小和图像 :

```typescript
const sandbox = await compute.instances.create({
  vcpu: 2,
  memoryMib: 6144,
  diskMb: 12000,
  image: 'builder',
});
```

| 选项 | 说明 |
| --- | --- |
| `vcpu` | a 包括一个 [自定义实例类型](https://developers.cloudflare.com/containers/platform/limits/#custom-instance-types) |
| `memoryMib` | 自定义实例类型的内存, 在 MiB 中 |
| `diskMb` | 自定义实例类型的磁盘, 以 MB 为单位 |
| `image` | 工人宣布的图像名称. `builder` 拥有节点24和常用的构建工具. |

设定 `vcpu`, (中文(简体) ), `memoryMib`,以及 `diskMb` 一起来 没有它们,沙盒会使用工人的默认实例类型. 无 `image`它使用工人的默认图像.

## 配置

```typescript
interface CloudflareConfig {
  /** URL of the deployed bridge Worker (or sandbox demo Worker) */
  sandboxUrl?: string;
  /** API key that matches the Worker's SANDBOX_API_KEY secret */
  sandboxApiKey?: string;
  /** Deprecated compatibility alias for sandboxApiKey */
  sandboxSecret?: string;
  /** Durable Object binding to the Worker's Sandbox class (direct mode only) */
  sandboxBinding?: any;
  /** Execution timeout in milliseconds (default 30,000; maximum 900,000) */
  timeout?: number;
  /** Environment variables to pass to sandbox commands */
  envVars?: Record<string, string>;
}
```

## 直接模式

如果你的代码已经运行在云旗工人,直接绑在 `Sandbox` 工人输出的持久对象 :

```jsonc
{
  "durable_objects": {
    "bindings": [
      {
        "name": "SANDBOX",
        "class_name": "Sandbox",
        "script_name": "sandbox"
      }
    ]
  }
}
```

然后,把装订 给提供者:

```typescript
import { cloudflare } from '@computesdk/cloudflare';

const compute = cloudflare({
  sandboxBinding: env.SANDBOX,
});
```

## 处理错误

```typescript
const result = await sandbox.runCommand('command-that-does-not-exist');
if (result.exitCode !== 0) {
  console.error(result.stderr);
}
```

## 限制

-   根据您的 Cloudflare 计划适用资源限制
-   一些系统调用在集装箱环境中可能受到限制
-   预览 URL 和快照需要桥接工作人, 而不能直接使用
-   不支持列出所有沙盒- 使用 `getById` 重新连接到特定的沙盒ID.

## 许可证

麻省理工学院

## 常见问题

### @computesdk/cloudflare 是什么？

Cloudflare 计算SDK 提供商 - 使用 Cloudflare 工人和持久对象执行边码

### 如何安装 @computesdk/cloudflare？

在项目目录运行 npm install @computesdk/cloudflare，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 computesdk-cloudflare，可以用 npx computesdk-cloudflare 直接运行。

### @computesdk/cloudflare 支持 TypeScript 吗？

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

### @computesdk/cloudflare 支持 ESM 还是 CommonJS？

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

### @computesdk/cloudflare 可以商用吗？

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

### @computesdk/cloudflare 的下载量有多少？

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

### @computesdk/cloudflare 还在维护吗？

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