要将应用从 Sandbox SDK 0.x 迁移到 1.0，请用你自己编写的 Durable Object 类替换 Sandbox 类。然后替换应用使用的每个 0.x 功能。你的类会启动使用 Durable Object 调度策略 的容器，该策略目前处于公开 Beta。有关这些变更的原因，请参阅 Sandbox SDK 1.0 中的变更。
使用 Durable Object 调度策略的 Containers 启动更快。在一项同时启动 100 个 sandbox 的独立基准测试中，从创建 sandbox 到在其中运行命令的中位时间从 4.0 秒降至 648 毫秒。测量详情请参阅 Cloudflare Containers，重构以扩展 Agent sandbox ↗。每次 start() 调用也会选择自己的镜像，部署不会重启正在运行的 sandbox。
Sandbox SDK 0.x 会持续提供缺陷与安全修复直到 2026-12-31，之后不再新增功能。该日期之后，已部署的 0.x 应用会继续运行，@cloudflare/sandbox 0.x 仍会留在 npm 上。
迁移页面将 1.0 与最后一个 0.x 版本 0.12 进行比较。如果你的应用使用更早版本，请先升级到 @cloudflare/sandbox 0.12.14 和 docker.io/cloudflare/sandbox:0.12.14 镜像。
你可以在一次部署中迁移所有 sandbox，也可以让 1.0 类与 0.x 类并排运行，然后一次迁移一个 sandbox。无论哪种方式，都先在预发布 Worker 上排练。要选择方式并为部署做准备，请参阅 规划迁移到 Sandbox SDK 1.0。
每个应用都需要下表中的前两页。要找到其余页面，请在源目录中搜索 0.x 调用：
grep -rhow \
-e getSandbox -e sleepAfter -e keepAlive \
-e envVars -e onStart -e onStop \
-e onActivityExpired -e createSession \
-e readFile -e writeFile -e listFiles -e watch \
-e startProcess -e streamProcessLogs \
-e exposePort -e proxyToSandbox -e wsConnect \
-e tunnels -e terminal -e SandboxAddon \
-e outboundByHost -e setOutboundHandler \
-e allowedHosts -e deniedHosts -e gitCheckout \
-e enableInternet -e interceptHttps \
-e mountBucket -e createBackup -e restoreBackup \
-e runCode -e createCodeContext \
-e sandbox/opencode -e sandbox/openai \
-e sandbox/bridge -e WarmPool \
src | sort | uniq -c该命令会打印它找到的每个名称及其出现次数。某些名称（例如 watch 和 terminal）也可能匹配不使用 SDK 的代码。0.12 的 codex-app-server 模板会打印：
1 enableInternet
6 getSandbox
1 gitCheckout
2 interceptHttps
1 outboundByHost
2 proxyToSandbox
1 readFile
2 sleepAfter
1 startProcess
1 writeFile每个名称对应一页：
| 0.x 代码 | 页面 | 1.0 中的工作 |
|---|---|---|
Sandbox, getSandbox(), sleepAfter, keepAlive, envVars, onStart(), onStop(), onActivityExpired() |
替换 Sandbox 类 | 编写该类 |
exec(), execStream(), createSession() |
更改命令调用 | 更改调用 |
readFile(), writeFile(), listFiles(), watch() |
更改文件调用 | 更改调用 |
startProcess(), streamProcessLogs() |
迁移后台进程 | 添加代码 |
exposePort(), proxyToSandbox(), wsConnect() |
迁移预览 URL | 添加代码 |
tunnels |
迁移隧道 | 添加代码 |
terminal(), SandboxAddon |
迁移浏览器终端 | 添加代码 |
outboundByHost, setOutboundHandler(), allowedHosts, deniedHosts, enableInternet, interceptHttps, gitCheckout() |
迁移出站规则 | 添加代码 |
mountBucket() |
迁移存储桶挂载 | 更改调用 |
createBackup(), restoreBackup() |
迁移备份 | 添加代码 |
runCode(), createCodeContext() |
替换代码解释器 | 添加代码 |
sandbox/opencode, sandbox/openai, sandbox/bridge, WarmPool |
迁移其他 0.x 功能 | 添加或移除代码 |
Dockerfile 中的 FROM docker:dind-rootless |
在 sandbox 内运行 Docker | 更改镜像 |
在预发布 Worker 上逐页完成这些工作，用你自己的检查进行测试，然后再部署到生产环境。有关每个 0.x API 及其替换项（包括在 1.0 中没有等价物的功能），请参阅 API 对照。
完成迁移之前，请将 @cloudflare/sandbox 固定为 0.12.14，并将镜像固定为 docker.io/cloudflare/sandbox:0.12.14。弃用公告列出了新工作中应避免使用的 0.x 功能：HTTP 和 WebSocket 传输、exposePort()、默认会话以及独立的流式传输方法。