# @computesdk/run-cloud 中文文档

规范地址：https://npmcn.com/package/%40computesdk/run-cloud/

版本：1\.0\.19
npm 元数据更新时间：2026-11-06T13:41:40.531Z
中文译文更新时间：2026-11-10T14:47:36.849Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1 MB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：3 个
- 首次发布：2026-08-10T19:47:21.712Z
- 最新版本发布：2026-11-06T13:41:40.305Z
- 近 30 天下载量：9029（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 19 个）

## 中文简介

运行 CricuteSDK 的 Cloud 提供者 - 有快照和文件系统访问的快活鞭炮微VM 沙盒

## 安装

```sh
npm install @computesdk/run-cloud
```

也可以使用：`pnpm add @computesdk/run-cloud`、`yarn add @computesdk/run-cloud`、`bun add @computesdk/run-cloud`

## README

# @computesdk/run-cloud (英语)

[运行云](https://run.cloud/) 计算SDK的提供者。 在可配置的CPU、内存和磁盘、本地文件读取、快照和自动闲置暂停的快速鞭炮微VM沙盒内运行命令.

## 安装

```bash
npm install computesdk @computesdk/run-cloud
```

在其中创建 API 密钥 [运行云盘](https://run.cloud/) 并导出 :

```bash
export RUN_CLOUD_API_KEY=rc_live_your_key
```

`RUN_CLOUD_API_TOKEN` 被支持为倒向兼容的别名。 设定 `RUN_CLOUD_API_URL` 仅在瞄准自定义运行云部署时.

## 使用量

```typescript
import { compute } from 'computesdk';
import { runCloud } from '@computesdk/run-cloud';

compute.setConfig({
  provider: runCloud({
    apiKey: process.env.RUN_CLOUD_API_KEY,
    cpu: 2,
    memory: 4096,
    disk: 40,
  }),
});

const sandbox = await compute.instances.create({
  templateId: 'runcloud/agent-base',
  name: 'agent-task',
});

const result = await sandbox.runCommand('node --version');
console.log(result.stdout);

await sandbox.filesystem.writeFile('/tmp/result.txt', result.stdout);
console.log(await sandbox.filesystem.readFile('/tmp/result.txt'));

const snapshot = await compute.snapshot.create(sandbox.instanceId, {
  name: 'after-setup',
});

await sandbox.destroy();

const restored = await compute.instances.create({
  snapshotId: snapshot.id,
  name: 'restored-task',
});
```

供应商工厂也可以直接使用:

```typescript
const cloud = runCloud({ apiKey: process.env.RUN_CLOUD_API_KEY });
const sandbox = await cloud.sandbox.create({ cpu: 1, memory: 1024 });
```

## 配置

```typescript
interface RunCloudConfig {
  apiKey?: string;
  apiUrl?: string;
  fetch?: typeof fetch;
  image?: string;
  cpu?: number;
  memory?: number;
  disk?: number;
  idlePauseSeconds?: number;
  timeout?: number;
  region?: string;
  orgId?: string;
  commandTimeout?: number;
  tunnelTtlSeconds?: number;
}
```

-   `cpu` 接受分数的 vCPU 值.
-   `memory` 以MIB计量.
-   `disk` 是 GiB 可写入的磁盘配额 .
-   `timeout` 财务报告和审定财务报表 `commandTimeout` 数以毫秒计.
-   `tunnelTtlSeconds` 控制公共端口 URL 寿命并默认为1小时.
-   `idlePauseSeconds` 秒; 设置为 `0` 以禁用自动暂停.
-   `templateId` 财务报告和审定财务报表 `image` 二者都选择已注册的 Run Cloud OCI 图像 .
-   `snapshotId` 恢复先前创建的“运行云”快照.
-   新鲜的创建接受每个创建 `cpu`, (中文(简体) ), `memory`, (中文(简体) ), `disk`, (中文(简体) ), `idlePauseSeconds`, (中文(简体) ), `timeoutSeconds`, (中文(简体) ), `region`, (中文(简体) ), `name`, (中文(简体) ), `orgId`,以及 `idempotencyKey` 超载.
-   快照恢复接受 `cpu`, (中文(简体) ), `memory`, (中文(简体) ), `disk`, (中文(简体) ), `timeoutSeconds`, (中文(简体) ), `region`, (中文(简体) ), 财务报告和审定财务报表 `name` 超载 无法应用的 API 选项被拒绝 而不是被无声地忽略.

运行 Cloud 目前不支持持久性沙盒级 `envs`。通过命令范围变量,变量为:

```typescript
await sandbox.runCommand('echo "$MODEL"', {
  env: { MODEL: 'gpt-5' },
});
```

## 支助业务

| 方法 | 支助 | 页:1 |
| --- | --- | --- |
| `create` | ✅ | 新鲜的图像启动或快照还原;恢复安全覆盖得到验证和应用. |
| `getById` | ✅ | 回返 `null` 当沙盒不存在时. |
| `list` | ✅ | 列出运行 API 密钥可见的沙盒 . |
| `destroy` | ✅ | 沙盒已经没了就更能说明问题了. |
| `runCommand` | ✅ | 支助 `cwd`, 命令- 范围化的 env, 超时, 流回调, 和离散的背景命令 . |
| `getInfo` | ✅ | 刷新运行云的状态和资源元数据 . |
| `getUrl` | ✅ | 打开过期的能力 URL而不使沙盒具有持久性 . |
| 文件系统 | ✅ | 原生读取; shell-backed write, mkdir, 列表, 存在并去除. |
| 抓图 | ✅ | 通过 `snapshotId`。 。 。 . |

`sandbox.getInstance()` 返回 a `RunCloudSandbox` 包含官员的控件 `Client` 和最新的本土沙盒记录.

隧道主机名是随机无记名能力. 不要把它们写到公共日志上. 它们自动过期,被删除隧道或沙盒后被移除.

## 常见问题

### @computesdk/run-cloud 是什么？

运行 CricuteSDK 的 Cloud 提供者 - 有快照和文件系统访问的快活鞭炮微VM 沙盒

### 如何安装 @computesdk/run-cloud？

在项目目录运行 npm install @computesdk/run-cloud，或使用 pnpm add / yarn add / bun add。

### @computesdk/run-cloud 支持 TypeScript 吗？

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

### @computesdk/run-cloud 支持 ESM 还是 CommonJS？

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

### @computesdk/run-cloud 需要什么版本的 Node\.js？

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

### @computesdk/run-cloud 可以商用吗？

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

### @computesdk/run-cloud 的下载量有多少？

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

### @computesdk/run-cloud 还在维护吗？

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