# @computesdk/superserve 中文文档

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

版本：0\.2\.20
npm 元数据更新时间：2026-11-06T13:39:36.064Z
中文译文更新时间：2026-11-10T14:29:09.953Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：93.7 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2026-06-29T20:11:41.193Z
- 最新版本发布：2026-11-06T13:39:35.677Z
- 近 30 天下载量：9542（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 21 个）

## 中文简介

Superserve提供沙盒基础设施,用于在由火花微VMs提供动力的孤立云环境中运行代码

## 安装

```sh
npm install @computesdk/superserve
```

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

## README

# @ computesdk/ 超级服务器

Superserve 提供在孤立云中运行代码的沙盒基础设施 由烟花微VMs提供动力的环境.

## 安装

```bash
npm install computesdk @computesdk/superserve
```

## 设置

1.  获取您的超级服务器 API 密钥 [控制台. 超级服务器.ai](https://console.superserve.ai/)。 。 。 .
2.  设置环境变量 :

```bash
export SUPERSERVE_API_KEY=your_api_key_here
```

## 快速启动

```typescript
import { compute } from 'computesdk';
import { superserve } from '@computesdk/superserve';

compute.setConfig({
  provider: superserve({ apiKey: process.env.SUPERSERVE_API_KEY }),
});

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

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

await sandbox.destroy();
```

或者直接给供货厂打电话:

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

const provider = superserve({ apiKey: process.env.SUPERSERVE_API_KEY });
const sandbox = await provider.sandbox.create();
```

## 配置

```typescript
superserve({
  apiKey: string,      // optional, falls back to SUPERSERVE_API_KEY
  baseUrl: string,     // optional, falls back to SUPERSERVE_BASE_URL,
                       //   then the @superserve/sdk default
  timeout: number,     // optional default auto-pause timeout (ms)
})
```

## 特征

| 特性 | 支助 |
| --- | --- |
| 沙盒生命周期( 创建 / 连接 / 列表 / 销毁) | ✅ |
| 命令使用 cwd、 env 和超时执行 | ✅ |
| 现场命令输出( L)`onStdout` 编号 : `onStderr`(中文(简体) ) | ✅ |
| 文件系统( 读取、 写入、 mkdir、 读取、 存在、 删除) | ✅ |
| 模板( 从命名模板启动) | ✅ |
| 快照( 创建、 列表、 删除、 从快照中启动) | ✅ |
| 预览 URL (`getUrl`(中文(简体) ) | ✅ |
| 暂停/ 恢复( 记忆、 进程和文件保存) | ✅ `instance.pause()` 编号 : `instance.resume()` |
| 模板构建( E)`template.create`(中文(简体) ) | 使用时间 `@superserve/sdk` `Template.create` |

## API 参考

### `sandbox.create(options?)`

启动一个新的微VM. 共同选项 :

```typescript
await compute.instances.create({
  templateId: 'superserve/python-3.11',    // optional, defaults to superserve/base
  timeout: 60_000,                          // auto-pause timeout in ms
  envs: { API_KEY: 'value' },
  name: 'my-sandbox',
  metadata: { source: 'ci' },
});
```

解析模板包括: `superserve/base`, (中文(简体) ), `superserve/python-3.11`, (中文(简体) ), `superserve/node-22`,等等——见 [超级服务器文件](https://docs.superserve.ai/) 完整名单.

过 `snapshotId` 改为 `templateId` 从快照启动(见 [抓图](https://npmcn.com/package/%40computesdk/superserve/#readme-snapshots)) (中文(简体) ).

### `sandbox.runCommand(command, options?)`

```typescript
const result = await sandbox.runCommand('npm install', {
  cwd: '/app',
  env: { NODE_ENV: 'production' },
  timeout: 120_000,
});

console.log(result.exitCode);
console.log(result.stdout);
console.log(result.stderr);
```

过 `onStdout` 编号 : `onStderr` 在命令运行时接收输出 :

```typescript
await sandbox.runCommand('npm test', {
  onStdout: (data) => process.stdout.write(data),
  onStderr: (data) => process.stderr.write(data),
});
```

### `sandbox.getUrl({ port })`

```typescript
await sandbox.runCommand('python3 -m http.server 8000', { background: true });
const url = await sandbox.getUrl({ port: 8000 });
```

`getUrl` 发布端口并返回其预览 URL。 已公布的端口为 默认公开。 港口必须在1024至65535之间;港口49983为 保留。 对于私人预览和访问符,请使用预览 API 打开 `sandbox.getInstance()` ——见: [预览 URL 指南](https://docs.superserve.ai/sandbox/preview-urls)。 。 。 .

### `sandbox.filesystem`

```typescript
await sandbox.filesystem.writeFile('/app/config.json', '{"key":"value"}');
const text = await sandbox.filesystem.readFile('/app/config.json');
await sandbox.filesystem.mkdir('/app/data');
const entries = await sandbox.filesystem.readdir('/app');
const present = await sandbox.filesystem.exists('/app/config.json');
await sandbox.filesystem.remove('/app/config.json');
```

`readFile` 财务报告和审定财务报表 `writeFile` 直接到每个沙盒的数据平面. `mkdir`, (中文(简体) ), `readdir`, (中文(简体) ), `exists`,以及 `remove` 通过 shell 执行 运行的命令 `sandbox.runCommand`。 。 。 .

### `sandbox.getInfo()` 编号 : `sandbox.destroy()`

```typescript
const info = await sandbox.getInfo();
console.log(info.id, info.status);

await sandbox.destroy();
```

状态映射:超级服务器 `paused` 财务报告和审定财务报表 `deleted` 报告状态为 计算SDK的 `stopped`, (中文(简体) ), `failed` 作为 `error`,其他各州为 `running`。 。 。 .

### `provider.sandbox.list()` 财务报告和审定财务报表 `getById(id)`

```typescript
const items = await provider.sandbox.list();      // read-only, no side effects
const sandbox = await provider.sandbox.getById(items[0].instanceId);
```

`list()` 仅读 —— 它返回 `InstanceInfo` 没有打开的根 届会。 要实际操作上市条目,请打电话 `getById(id)`。 。 。 .

请注意: `getById()` 问题 `POST /activate` 沙盒上那个 **自动复调已暂停的沙盒** 并旋转他们的访问标志。 狦 仅需要只读元数据,更喜欢重复 `list()` 直接说.

### 模板

```typescript
const templates = await provider.template!.list();
```

改为: **创建** 模板,使用 `@superserve/sdk` 直接——模板 需要一个构建的 spec (`from` + 键 `steps`),计算SDK `template.create({ name })` 形状不携带.

### 抓图

```typescript
const snapshot = await provider.snapshot!.create(sandbox.instanceId, {
  name: 'before-upgrade',
});

// Boot a new sandbox from it; processes that were running continue.
const fork = await provider.sandbox.create({ snapshotId: snapshot.id });

const snapshots = await provider.snapshot!.list({ instanceId: sandbox.instanceId });
await provider.snapshot!.delete(snapshot.id);
```

一个快照可以保存沙盒的内存和磁盘,并保存到删除时,甚至 在原始沙盒消失之后。 每个沙盒列出快照:通过 `instanceId` 改为 `list()`,它返回一个没有它的空列表. `snapshot.create()` 首先连接到沙盒, 如果是, 沙盒会恢复它 暂停 见 [示意图指南](https://docs.superserve.ai/sandbox/snapshots)。 。 。 .

## 处理错误

常见错误和如何回收 :

```typescript
try {
  const sandbox = await compute.instances.create();
} catch (error) {
  const msg = error instanceof Error ? error.message : String(error);

  if (msg.includes('authentication')) {
    // Bad or missing SUPERSERVE_API_KEY
  } else if (msg.includes('quota') || msg.includes('limit')) {
    // Team has hit its concurrent-sandbox cap
  } else {
    // Network or transient platform error — safe to retry with backoff
  }
}
```

认证失败归正为单一的用户信息 不论根本原因(HTTP 401, 缺少密钥, `AuthenticationError` 从SDK.

## 实例

一个可运行的示例 [`examples/basic`](https://npmcn.com/package/examples/basic)数字 :

```bash
cd examples/basic
export SUPERSERVE_API_KEY=your_key
pnpm superserve
```

## 学多点

-   [超级服务器文件](https://docs.superserve.ai/)
-   [`@superserve/sdk`](https://www.npmjs.com/package/@superserve/sdk)
-   [计算SDK](https://github.com/computesdk/computesdk)

## 许可证

麻省理工学院

## 常见问题

### @computesdk/superserve 是什么？

Superserve提供沙盒基础设施,用于在由火花微VMs提供动力的孤立云环境中运行代码

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

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

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

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

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

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

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

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

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

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

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

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