2026 弃用迁移指南

本指南介绍如何从 2026 年 6 月弃用的 Sandbox SDK 功能迁移出去。这些功能在 2026 年 7 月 9 日之后的 Sandbox SDK 版本中将不再存在。

有关公告和原因，请参阅弃用更新日志条目。

迁移前

在更改传输或会话配置之前，请先更新到最新的 Sandbox SDK 版本。如果你的项目使用的版本早于 0.9.1，请在切换到 RPC 传输之前部署较新的 @cloudflare/sandbox 包和 container 镜像。

在代码库中搜索已弃用的配置和 API：

rg 'SANDBOX_TRANSPORT|transport:|exposePort\(|enableDefaultSession|execStream\(|readFileStream|writeFileStream'

同时检查任何使用流式文件专用辅助方法的代码，或依赖 shell 状态在单独的 exec() 调用之间保持的代码。

HTTP 和 WebSocket 传输

在 2026 年 7 月 9 日之后发布的 Sandbox SDK 版本中，HTTP 和 WebSocket 传输将不再存在。请在该日期前切换到 RPC 传输。

要为 Worker 中的每个沙箱配置 RPC 传输，请在 Worker 配置中设置 SANDBOX_TRANSPORT：

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

[vars]
SANDBOX_TRANSPORT = "rpc"

要为特定沙箱配置 RPC 传输，请向 getSandbox() 传入 transport: "rpc"：

import { getSandbox } from "@cloudflare/sandbox";

const sandbox = getSandbox(env.Sandbox, "user-123", {
	transport: "rpc",
});

更多信息请参阅传输模式。

Desktop

桌面功能已在 0.10.2 中移除。如果你的应用使用了 Sandbox SDK 桌面 API 进行浏览器自动化，请将该浏览器自动化迁移到 Cloudflare Browser Run。

继续使用 Sandbox SDK 进行隔离命令执行、文件操作以及不需要完整远程浏览器环境的运行时工作流。

暴露端口

将 exposePort() 替换为 tunnels API 以获取公共 URL。tunnels API 需要 RPC 传输。

开发、演示和短期 URL 使用 quick tunnels。生产流量、webhook 接收器、OAuth 回调以及你控制的 zone 上的稳定主机名使用 named tunnels。

import { getSandbox } from "@cloudflare/sandbox";

const sandbox = getSandbox(env.Sandbox, "my-sandbox", {
	transport: "rpc",
});

const server = await sandbox.startProcess("python -m http.server 8080");
await server.waitForPort(8080);

const tunnel = await sandbox.tunnels.get(8080);
return Response.json({ url: tunnel.url });

如果你的 exposePort() 流程使用了 proxyToSandbox() 注入身份验证或重写响应，在将公共 URL 迁移到 tunnel 之前请先考虑这些行为。

更多信息请参阅 Tunnels 和暴露服务。

默认会话

在 getSandbox() 上设置 enableDefaultSession: false。之后，没有显式会话的操作将以隔离方式运行，且不会继承先前调用的 shell 状态。

import { getSandbox } from "@cloudflare/sandbox";

const sandbox = getSandbox(env.Sandbox, "user-123", {
	enableDefaultSession: false,
	transport: "rpc",
});

如果你的代码期望类似 cd /workspace/app 的命令影响后续 exec() 调用，请创建显式会话并通过该会话运行相关命令：

const buildSession = await sandbox.createSession({
	id: "build",
	cwd: "/workspace/app",
});

await buildSession.exec("npm install");
await buildSession.exec("npm test");

对于一次性命令，请直接向 exec() 传入 cwd 或 env，而不是依赖持久化的 shell 状态：

await sandbox.exec("npm test", {
	cwd: "/workspace/app",
	env: {
		NODE_ENV: "test",
	},
});

更多信息请参阅 Sandbox 选项和 Sessions。

流式 API

Sandbox SDK 正在将独立的流式 API 整合到基础的 exec()、readFile() 和 writeFile() 方法中。请审查依赖流专用辅助方法的代码，并在基础 API 支持流式行为的情况下迁移到这些 API。

对于命令输出，使用带流式回调的 exec()：

await sandbox.exec("npm install", {
	stream: true,
	onOutput: (stream, data) => {
		console.log(`[${stream}] ${data}`);
	},
});

对于大型或二进制文件，使用带 RPC 传输的基础文件 API。向 writeFile() 传入 ReadableStream，或使用 encoding: "none" 以流的形式读取文件：

const request = await fetch("https://example.com/archive.tar.gz");

if (!request.body) {
	throw new Error("Expected archive response body");
}

await sandbox.writeFile("/workspace/archive.tar.gz", request.body);

const file = await sandbox.readFile("/workspace/archive.tar.gz", {
	encoding: "none",
});

return new Response(file.content, {
	headers: { "Content-Type": file.mimeType },
});

更多信息请参阅 Commands 和 Files。

验证迁移

在升级到 2026 年 7 月 9 日之后发布的 Sandbox SDK 版本之前，请使用此清单：

已使用 SANDBOX_TRANSPORT=rpc 或 transport: "rpc" 配置 RPC 传输。
不再保留 websocket 或 http 传输配置。
迁移路径中不再有 exposePort() 用法。
enableDefaultSession 已设为 false。
有状态的命令工作流使用 sandbox.createSession()。
一次性命令直接传入 cwd 和 env。
流式文件和命令代码使用基础 API。
你的 Worker 已部署并通过冒烟测试。

Agent 技能

有一个 Agent 技能可协助迁移：SKILL.md。