# @adobe/aio-lib-sandbox 中文文档

规范地址：https://npmcn.com/package/%40adobe/aio-lib-sandbox/

版本：0\.1\.0-alpha\.12
npm 元数据更新时间：2026-10-01T01:32:30.115Z
中文译文更新时间：2026-11-05T22:04:25.176Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：136 kB，20 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=18
- 运行依赖：1 个
- 首次发布：2026-05-27T16:28:16.399Z
- 最新版本发布：2026-09-03T21:53:06.045Z
- 近 30 天下载量：14071（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

Adobe 运行时沙盒的 JavaScript SDK

## 安装

```sh
npm install @adobe/aio-lib-sandbox
```

也可以使用：`pnpm add @adobe/aio-lib-sandbox`、`yarn add @adobe/aio-lib-sandbox`、`bun add @adobe/aio-lib-sandbox`

## README

# 应用构建器 SDK

[![Version](https://img.shields.io/npm/v/@adobe/aio-lib-sandbox.svg)](https://npmjs.org/package/@adobe/aio-lib-sandbox) [![Downloads/week](https://img.shields.io/npm/dw/@adobe/aio-lib-sandbox.svg)](https://npmjs.org/package/@adobe/aio-lib-sandbox) ![Node.js CI](https://github.com/adobe/aio-lib-sandbox/workflows/Node.js%20CI/badge.svg) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Codecov Coverage](https://img.shields.io/codecov/c/github/adobe/aio-lib-sandbox/main.svg?style=flat-square)](https://codecov.io/gh/adobe/aio-lib-sandbox/)

JavaScript SDK 为 Adobe runtime Sandboxs 所使用.

A 类 **沙盒** 是一种与世隔绝的计算环境。 您创建一个, 运行命令并读取/ 写入文件, 然后销毁它 .

## 先决条件

要使用此库, 您必须启用 Sandboxs 为您的运行时命名空间 。 请联系迈克尔·戈伯林(Michael Goberling)[mgoberling@adobe.com (英语)](mailto:mgoberling@adobe.com)或科斯敏·斯坦西乌(Cosmin Stanciu)[时间轴: stanciu@adobe.com](mailto:stanciu@adobe.com)要求这样做.

## 安装

```bash
npm install @adobe/aio-lib-sandbox
```

## 快速启动

在运行时动作内部,不需要配置来使用SDK,因为证书是从环境中自动读取的.

```js
const { Sandbox } = require('@adobe/aio-lib-sandbox')

async function main (params) {
  const sandbox = await Sandbox.create({ name: 'my-sandbox' })

  const { stdout } = await sandbox.exec('node --version', { timeout: 10_000 })

  await sandbox.destroy()
  return { stdout: stdout.trim() }
}

exports.main = main
```

## 配置

当运行在运行时间动作内时, SDK 自动读取来自环境的证书 :

| 变量 | 说明 |
| --- | --- |
| `__OW_API_HOST` | 运行时间 API 主机 |
| `__OW_NAMESPACE` | 运行时命名空间 |
| `__OW_API_KEY` | 运行时间 API 密钥( 基本认证) |

你可以通过直接传递到 `Sandbox.create()` 或者说 `Sandbox.get()`数字 :

```js
const sandbox = await Sandbox.create({
  apiHost:   'https://adobeioruntime.net',
  namespace: 'my-namespace',
  auth:    'my-api-key',
  name:      'my-sandbox'
})
```

## 使用量

### 创建沙盒

```js
const { Sandbox } = require('@adobe/aio-lib-sandbox')

const sandbox = await Sandbox.create({
  name:        'my-sandbox',
  region:      'va6',
  type:        'cpu:default',
  idleTimeout: 900,
  maxLifetime: 3600,
  ports:       [3000, 8080],
  envs:        { API_KEY: 'your-api-key' }
})
```

Canonical sandbox API主机为纬度路由并可以发送请求到外接组 区域名称。 何时 `region` 设置, SDK 由此引导犬类主机 直接到那个区域终点。 区域标识符使用2到4个字母,然后是1或 二位数,并改为小写。 自定义和已经区域 `apiHost` 值为左 不变。 选择 `region` 保存默认的 latency 路由 API 主机行为 .

#### 沙盒寿命模型

沙盒总是被删除 `maxLifetime` 已经过去了。 还将在 `idleTimeout` 已经过去了,如果没有活动.

保存沙盒, 发送至少一个命令或检查状态 `idleTimeout` 秒数.

### 获取状态

```js
const sandbox = await Sandbox.get(sandbox.id)
console.log('status:', sandbox.status)
```

### 执行

```js
const result = await sandbox.exec('ls -al', { timeout: 10_000 })
console.log('stdout:', result.stdout.trim())
console.log('exit code:', result.exitCode)
```

> 注:在 `/workspace` 默认目录, 无法配置

### 已删除的命令

过 `detached: true` 以运行一个长寿的背景进程.

```js
// Start a background server
const command = await sandbox.exec('node server.js', { detached: true })

// Wait for it to exit (e.g. after you stop it)
const result = await command.wait()
console.log('exit code:', result.exitCode)

// Send a signal to stop it
await command.kill()
```

如果进程还在运行中, 您需要从不同的上下文获得一个手柄, 请使用 `getCommand()` 以重新连接 `execId`数字 :

```js
const command = await sandbox.getCommand(execId, { onOutput: (data, stream) => process.stdout.write(data) })
await command.wait()
```

> 注:目前只允许5个背景进程同时运行.

### 文件管理

```js
const script = "console.log('hello from sandbox script', process.version)\n"
await sandbox.writeFile('hello.js', script)

const content = await sandbox.readFile('hello.js')
console.log('readFile content:', content.trim())

const entries = await sandbox.listFiles('.')
console.log('listFiles entries:', entries)
```

### 执行文件

```js
const result = await sandbox.exec('node hello.js', { timeout: 10_000 })
console.log('stdout:', result.stdout.trim())
console.log('stderr:', result.stderr.trim())
console.log('exit code:', result.exitCode)
```

### 写入 Stdin

#### 开始命令

```js
const result = await sandbox.exec('node process_csv.js', {
  stdin: 'col1,col2\nval1,val2\n',
  timeout: 10_000
})
console.log('stdout:', result.stdout.trim())
```

#### 运行中的命令

```js
const task = sandbox.exec('cat -n', { timeout: 10_000 })

sandbox.writeStdin(task.execId, 'line 1\n')
sandbox.writeStdin(task.execId, 'line 2\n')
sandbox.closeStdin(task.execId)

const result = await task
console.log('stdout:', result.stdout.trim())
```

### 销毁

```js
await sandbox.destroy()
```

### 预览 URL

应向公众开放的港口必须在创建时通过 `ports` 阵列.

```js
const sandbox = await Sandbox.create({
  name:  'web-sandbox',
  ports: [3000, 8080]
})

// Start a server inside the sandbox on the declared port
await sandbox.exec('node server.js &', { timeout: 50_000 })

// Retrieve the pre-provisioned preview URL — synchronous, no network call
const url = sandbox.getUrl(3000)
console.log('preview:', url)
// https://sb-abc123-va6-0-xK3mPq2nAeB-3000.sandbox-adobeioruntime.net
```

## 网络政策

沙盒是默认的 除非明确允许,否则所有出入境交通均被封锁.

传出 a `policy.network.egress` 数组在创建时允许将输出的终点、路径或HTTP动词列出.

```js
const sandbox = await Sandbox.create({
  name:        'policy-sandbox',
  maxLifetime: 300,
  policy: {
    network: {
      egress: [
        { host: 'httpbin.org', port: 443 },
        {
          host: 'api.github.com',
          port: 443,
          rules: [
            { methods: ['GET'], pathPattern: '/repos/**' }
          ]
        }
      ]
    }
  }
})
```

## 发展

安装开发依赖性 :

```bash
npm install
```

要运行 CI 所用的相同检查 :

```bash
npm test
```

Linting由ESLint提供动力:

```bash
npm run lint
npm run lint-fix
```

## 常见问题

### @adobe/aio-lib-sandbox 是什么？

Adobe 运行时沙盒的 JavaScript SDK

### 如何安装 @adobe/aio-lib-sandbox？

在项目目录运行 npm install @adobe/aio-lib-sandbox，或使用 pnpm add / yarn add / bun add。

### @adobe/aio-lib-sandbox 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/adobe\_\_aio-lib-sandbox 是否存在。

### @adobe/aio-lib-sandbox 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @adobe/aio-lib-sandbox 需要什么版本的 Node\.js？

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

### @adobe/aio-lib-sandbox 可以商用吗？

@adobe/aio-lib-sandbox 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @adobe/aio-lib-sandbox 的下载量有多少？

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

### @adobe/aio-lib-sandbox 还在维护吗？

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