传输模式

使用传输模式配置 Sandbox SDK 与容器的通信方式。

Sandbox SDK 支持三种在 Durable Object 与容器之间通信的传输模式：

• HTTP 传输（默认）- 每次 SDK 操作都会向容器发起单独的 HTTP 请求。
• 新：RPC 传输 - 所有 SDK 操作通过单个持久 WebSocket 连接多路复用。未来将取代 HTTP 成为默认传输。自 0.9.1 起可用。
• 已弃用：WebSocket 传输 - 所有 SDK 操作通过单个持久 WebSocket 多路复用。已被使用改进协议的 RPC 传输取代。

当 Worker 或 Durable Object 在每个请求中执行大量 SDK 操作时，请使用 RPC 传输。这可避免触及子请求限制。

Cloudflare Workers 在向外部服务（包括容器 API 调用）发出请求时适用子请求限制：

• Workers Free：每个请求 50 个子请求
• Workers Paid：每个请求 1,000 个子请求

使用 HTTP 传输（默认）时，每次 SDK 操作（exec()、readFile()、writeFile() 等）都会消耗一个子请求。在单个请求中执行大量 sandbox 操作的应用可能触及这些限制。

RPC 传输与容器建立单个持久连接，并在其上多路复用所有 SDK 操作。WebSocket 升级计为 一个子请求，无论之后执行多少操作。

HTTP 传输示例（4 个子请求）：

await sandbox.exec("python setup.py");
await sandbox.writeFile("/app/config.json", config);
await sandbox.exec("python process.py");
const result = await sandbox.readFile("/app/output.txt");

相同代码使用 RPC 传输（1 个子请求）：

// Identical code - transport is configured via environment variable
await sandbox.exec("python setup.py");
await sandbox.writeFile("/app/config.json", config);
await sandbox.exec("python process.py");
const result = await sandbox.readFile("/app/output.txt");

RPC 传输还消除了 HTTP 传输存在的 32 MiB 限制。可将 ReadableStream 实例传递给 writeFile() 方法。

const req = await fetch("https://example.com/archive.tar.gz");
await sandbox.writeFile("/archive.tar.gz", req.body);

在 Worker 配置中设置 SANDBOX_TRANSPORT 环境变量。SDK 从 Worker 环境绑定读取该变量（而非容器内部）。

HTTP 传输为默认模式，无需额外配置。

通过将 SANDBOX_TRANSPORT 添加到 Worker 的 vars 来启用 RPC 传输：

{
	"name": "my-sandbox-worker",
	"main": "src/index.ts",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"vars": {
		"SANDBOX_TRANSPORT": "rpc"
	},
	"containers": [
		{
			"class_name": "Sandbox",
			"image": "./Dockerfile",
		},
	],
	"durable_objects": {
		"bindings": [
			{
				"class_name": "Sandbox",
				"name": "Sandbox",
			},
		],
	},
}

name = "my-sandbox-worker"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-08-17"

[vars]
SANDBOX_TRANSPORT = "rpc"

[[containers]]
class_name = "Sandbox"
image = "./Dockerfile"

[[durable_objects.bindings]]
class_name = "Sandbox"
name = "Sandbox"

无需更改应用代码。SDK 会自动对所有操作使用已配置的传输。

HTTP 传输：

• 每次 SDK 操作创建新的 HTTP 请求
• 无持久连接
• 每个请求独立且无状态

RPC 传输：

• 在首次 SDK 操作时建立 WebSocket 连接
• 为所有后续操作维护持久连接
• sandbox 休眠或被驱逐时关闭连接
• 连接断开时自动重连

所有传输都支持流式操作（例如带实时输出的 exec()）：

• HTTP 传输 - 使用 Server-Sent Events (SSE)
• RPC 传输 - 使用 WebSocket 流式消息

无论传输模式如何，你的代码保持相同。

所有传输提供相同的错误处理行为。SDK 会在瞬时错误（如 503 响应）时以指数退避自动重试。

WebSocket 特定行为：

• 连接失败会触发自动重连
• SDK 透明处理 WebSocket 断开
• 重连期间进行中的操作不会丢失

我们预计 RPC 传输将在未来版本中取代默认的 HTTP 传输。新功能可能仅支持 RPC 传输。现在切换可避免将来迁移。

在传输之间切换无需更改代码。

将 SANDBOX_TRANSPORT 添加到 wrangler.jsonc：

{
	"vars": {
		"SANDBOX_TRANSPORT": "rpc"
	},
}

[vars]
SANDBOX_TRANSPORT = "rpc"

然后部署：

npx wrangler deploy

移除 SANDBOX_TRANSPORT 变量（或将其设为 "http"）：

{
	"vars": {
		// Remove SANDBOX_TRANSPORT or set to "http"
	},
}

vars = { }

将 SANDBOX_TRANSPORT 变量设为 "rpc"：

{
	"vars": {
		"SANDBOX_TRANSPORT": "rpc"
	},
}

[vars]
SANDBOX_TRANSPORT = "rpc"

• Wrangler 配置 - 完整的 Worker 配置
• 环境变量 - 向 sandbox 传递配置
• Workers 子请求限制 - 了解子请求限制
• 架构 - Sandbox SDK 组件如何通信