连接沙箱-函数计算(FC)-阿里云帮助中心

当需要从不同进程或客户端访问同一个沙箱实例时，可通过 Sandbox.connect() 方法连接到已有的运行中沙箱，实现会话恢复与多客户端共享。本文介绍连接沙箱的方法、参数说明及典型使用场景。

功能说明

Sandbox.connect() 通过沙箱的唯一标识符（sandbox_id）连接到一个已经创建的沙箱实例。连接后返回的沙箱对象与 Sandbox.create() 返回的对象具有相同的操作能力，支持执行命令、读写文件等全部操作。

连接时，SDK 会重新设置沙箱的超时时间（使用创建时的 timeout 值或 SDK 默认的 300 秒）。沙箱内的文件系统和进程状态保持连续——之前写入的文件和启动的后台进程在连接后仍然可用。

前提条件

已安装 E2B SDK（Pythonpip install e2b==2.26.0 ；TypeScript：npm i e2b@2.28.0）
已获取 E2B API Key，并通过环境变量 E2B_API_KEY 设置
已有一个处于 running 状态的沙箱实例。可通过 Sandbox.create() 创建新沙箱，或通过 Sandbox.list() 查询已有沙箱

重要

connect() 只能连接正在运行的沙箱。如果沙箱已超时销毁或被 kill，连接会失败并抛出异常。
连接操作不会延长沙箱的存活时间。如果沙箱即将超时，请在连接后调用 set_timeout() / setTimeout() 续期。

连接沙箱

以下示例展示如何先创建沙箱获取 sandbox_id，再从其他进程或客户端重新连接同一沙箱并执行命令。

说明

代码示例中的 timeout（Python）和 timeoutMs（TypeScript）是 Sandbox.create() 的参数，用于设置沙箱创建超时时间，并非 Sandbox.connect() 的参数。

Python 示例

from e2b import Sandbox

# 先创建沙箱获取 sandbox_id
sandbox = Sandbox.create(
    template="base",
    api_key=E2B_API_KEY,
    timeout=600,
    **E2B_CONN_OPTS,
)
sid = sandbox.sandbox_id
print(f"Created sandbox: {sid}")

# 在其他地方连接同一个沙箱
reconnected = Sandbox.connect(sid, api_key=E2B_API_KEY, **E2B_CONN_OPTS)
result = reconnected.commands.run("echo 'reconnected!'")
print(result.stdout)
reconnected.kill()

TypeScript 示例

import { Sandbox } from 'e2b';

// 先创建沙箱获取 sandboxId
const sandbox = await Sandbox.create({
  template: 'base',
  apiKey: process.env.E2B_API_KEY!,
  timeoutMs: 600_000,
});
const sid = sandbox.sandboxId;
console.log(`Created sandbox: ${sid}`);

// 连接已有沙箱
const reconnected = await Sandbox.connect(sid, {
  apiKey: process.env.E2B_API_KEY!,
});
const result = await reconnected.commands.run('echo "reconnected!"');
console.log(result.stdout);
await reconnected.kill();

预期输出

Created sandbox: {sid}：沙箱创建成功，输出沙箱唯一标识符。
reconnected!：连接成功，已准备好执行命令。

使用场景

场景	说明
会话恢复	客户端断开后重新连接同一沙箱，继续之前的操作
多客户端共享	多个客户端同时连接同一沙箱，协作执行任务
跨进程协作	一个进程创建沙箱并传递 `sandbox_id`，另一个进程连接并执行操作

参数说明

参数	类型	必填	说明
`sandbox_id` / `sandboxId`	string	是	目标沙箱的唯一标识符，通过 `Sandbox.create()` 或 `Sandbox.list()` 获取
`api_key` / `apiKey`	string	是	E2B API Key，用于身份认证
`E2B_CONN_OPTS`（Python）	dict	否	可选的连接配置项，通常包含 `api_url`（API 服务地址，如 `https://api.cn-beijing.e2b.fc.aliyuncs.com`）和 `domain`（沙箱域名后缀，如 `cn-beijing.e2b.fc.aliyuncs.com`）
`timeout`	int	否	连接后重新设置的超时时间（秒）。不传时使用 SDK 默认值（300 秒）。从连接时刻起重新计时

故障排除

问题现象	可能原因	处理方法
连接失败，抛出异常	沙箱不存在或已被销毁	确认 `sandbox_id` 正确，通过 `Sandbox.list()` 查询沙箱是否仍在运行
连接失败，抛出异常	沙箱不在 running 状态	沙箱可能已超时或被手动终止，需重新创建沙箱
连接失败，认证错误	API Key 无效或过期	检查 `E2B_API_KEY` 环境变量是否正确配置，必要时在 E2B 平台重新生成

说明

连接前可通过 Sandbox.list() 确认目标沙箱仍在运行，避免盲目连接导致异常。

多客户端并发安全

多个客户端可同时连接同一沙箱，但需注意命令执行和文件操作的并发安全性。