# @computesdk/microsandbox 中文文档

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

版本：0\.1\.26
npm 元数据更新时间：2026-11-09T21:04:16.383Z
中文译文更新时间：2026-11-10T14:25:48.698Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：217 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：3 个
- 首次发布：2026-08-18T18:22:40.967Z
- 最新版本发布：2026-11-09T21:04:16.063Z
- 近 30 天下载量：10208（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 26 个）

## 中文简介

带有本地和云微VM后端的计算SDK微软盒提供商

## 安装

```sh
npm install @computesdk/microsandbox
```

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

## README

# @computesdk/microsandbox (英语)

计算SDK的Microsandbox提供商. 它运行相同的沙盒API来对抗被硬件同化的本地微VM或微沙盒云.

## 所需资源

-   22号节点或更新
-   云后端:微软箱云访问和API密钥
-   本地后端: 苹果硅上的 macOS, 有 KVM 的 Linux, 或 Windows 有 Windows Hypervisor 平台的 Windows

## 安装

```bash
npm install computesdk @computesdk/microsandbox
```

## 云快开始

云是默认后端. 直接传递一个 API 密钥或省略该密钥以使用 SDK 的微软盒 `MSB_API_KEY`, (中文(简体) ), `MSB_PROFILE`,或主动曝光分辨率:

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

compute.setConfig({
  provider: microsandbox({
    apiKey: process.env.MSB_API_KEY,
    image: 'node:22',
  }),
});

const sandbox = await compute.instances.create();
const result = await sandbox.runCommand('node --version');
console.log(result.stdout);
await sandbox.destroy();
```

## 本地快速启动

明确选择本地后端, 当沙盒在呼叫机上运行时 。 本地模式不需要账户或 API 密钥 :

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

compute.setConfig({
  provider: microsandbox({
    backend: 'local',
    image: 'node:22',
    ports: [{ host: 3000, guest: 3000 }],
  }),
});

const sandbox = await compute.instances.create();
await sandbox.filesystem.writeFile('/tmp/hello.js', 'console.log("hello")');
console.log((await sandbox.runCommand('node /tmp/hello.js')).stdout);
await sandbox.destroy();
```

通话 `microsandbox()` 没有配置则通过微软盒SDK的标准环境和活性可视分辨率使用云. 如果没有云证书解, 提供者报告如何配置云或选择加入 `backend: 'local'`它从不默默地回到当地.

酌情使用命名的云配置文件而不是 API 密钥 :

```typescript
const provider = microsandbox({ profile: 'production' });
```

## 配置

```typescript
interface MicrosandboxConfig {
  backend?: 'cloud' | 'local'; // Defaults to cloud
  apiKey?: string;             // Falls back to MSB_API_KEY
  apiUrl?: string;             // Optional endpoint override; requires apiKey
  profile?: string;            // Named cloud profile; mutually exclusive with apiKey/apiUrl
  image?: string;
  cpus?: number;
  memoryMib?: number;
  rootDiskMib?: number;
  ephemeral?: boolean;         // Delete on stop; defaults to true
  workdir?: string;
  namePrefix?: string;
  ports?: Array<number | { host: number; guest: number; bind?: string }>;
  timeout?: number;           // Idle and command timeout in milliseconds; defaults to 900_000 (15 minutes)
  pullPolicy?: 'always' | 'if-missing' | 'never';
  networkEnabled?: boolean;
}
```

单放箱 `image`, (中文(简体) ), `templateId`, (中文(简体) ), `snapshotId`, (中文(简体) ), `cpus`, (中文(简体) ), `vcpus`, (中文(简体) ), `memory`, (中文(简体) ), `memoryMb`, (中文(简体) ), `memoryMiB`, (中文(简体) ), `memoryMib`, (中文(简体) ), `memMiB`, (中文(简体) ), `rootDiskMib`, (中文(简体) ), `ephemeral`, (中文(简体) ), `timeout`, (中文(简体) ), `name`, (中文(简体) ), `envs`, (中文(简体) ), `metadata`,以及 `ports` 选项可酌情推翻或扩展提供者的默认.

## 后端支持

业务同时使用选定的全过程后端运行. 在服务商运行时不要更改本地 SDK 默认后端 .

| 方法 | 当地 | 云头 |
| --- | --- | --- |
| `create`, (中文(简体) ), `getById`, (中文(简体) ), `list`, (中文(简体) ), `destroy` | 对 | 对 |
| `runCommand` 和活输出回调 | 对 | 对 |
| `filesystem` | 对 | 对 |
| `getInfo` | 对 | 对 |
| `getUrl` | 是, 对于创建前已声明的端口 | 目前没有 |
| `snapshot` | 是, 磁盘状态 | 目前没有 |

本地快照停止了沙盒,捕获其可写取的根盘并重新启动. 该磁盘上的文件在恢复后幸存, 但 tmpfs 路径例如 `/tmp` 和运行的流程不被捕获。 Microsandbox 云目前不支持已发布的端口或磁盘快照,因此这些方法在云上返回明显不支持的错误.

## 许可证

麻省理工学院

沙盒默认为麻黄,停放时被删除. 他们的默认闲置超时为15分钟,通过本地 SDK 配置 `idleTimeout(900)`设置 `ephemeral: false` 在停止后保留沙盒,并使用 `timeout` (milliseconds)来覆盖闲置的超时和默认的命令超时. 适配器没有设定最长寿命.

每个进程使用一个后端配置. 同时期操作共享该配置;第一个成功的后端选择保留在进程的寿命. 后来有不同资质,端点,配置文件或后端选择的请求在更改SDK后端前被否决. 各地使用相同的显式配置,或始终使用SDK环境/显式分辨率.

## 常见问题

### @computesdk/microsandbox 是什么？

带有本地和云微VM后端的计算SDK微软盒提供商

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

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

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

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

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

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

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

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

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

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

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

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

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

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