Sandbox SDK 1.0 中的变更

在 Sandbox SDK 0.x 中，包中的 Sandbox 类就是你的 Durable Object。它启动容器、保持容器运行，并将每次调用发送到容器内的服务器。在 1.0 中，你编写 Durable Object 类，并通过 this.ctx.container 直接调用容器。

this.ctx.container 完成了 0.x SDK 服务器所做的工作。它运行命令、连接到端口、拦截出站请求并保存快照。该包只保留小型 helper，例如 Files 类。

取决于你应用的决策留在你的代码中：sandbox 运行多久、它可以访问什么，以及调用失败时会发生什么。例如，已取消的命令可能已经更改了文件，只有你的应用知道再次运行它是否安全。

每个 0.x 功能会移到三处之一，取决于 0.x 中哪一部分完成了它的工作：

• Sandbox 类处理生命周期、预览 URL、隧道、备份和进程跟踪。在 1.0 中，这些成为你 Durable Object 类中的代码，该类将所需记录保存在自己的存储中。
• SDK 服务器运行命令、会话和文件调用。在 1.0 中，这些成为 exec() 调用，或对 Files 类的调用，后者通过 exec() 运行 sandbox-shim helper。
• Wrangler 配置和类属性设置镜像、Internet 访问和出站规则。在 1.0 中，这些成为 start() 的选项，以及你的类注册的出站 handler。

某些 0.x 功能没有等价物。有关每个 0.x API 及其替换项，请参阅 API 对照。

除非 start() 传入 enableInternet: true，否则容器没有 Internet 访问。要允许一个目标，你的类为其主机名注册出站 handler。handler 可以添加容器永远看不到的凭据。更多信息请参阅 Sandbox 安全。

exec() 接受参数数组，并在不使用 shell 的情况下启动该进程。作为参数传入的文本无法启动第二条命令。只有在你启动 shell 时才会运行 shell，例如 ["sh", "-c", "npm ci && npm test"]。每次调用也设置自己的 cwd 和 env。没有会话会把它们从一次调用带到下一次。

你的类会在 start() 后设置不活动超时，以决定 sandbox 运行时长；当重启后的 Durable Object 发现容器正在运行时，也会在构造函数中再次设置超时。部署不会替换正在运行的容器。新镜像只会应用到部署后启动的容器。仅在启动容器时运行的类代码（例如注册出站处理程序的调用）也是如此。已注册的处理程序会运行新版本的代码，并使用注册时传入的 props。更多信息请参阅 Sandbox 生命周期。

你的镜像必须包含命令使用的所有工具。0.x 镜像包含 Python、Git、curl、wget、jq、unzip 和 ps。本指南使用的 cloudflare/debian-trixie 和 node:24-trixie-slim 均不包含这些工具。Files、S3Mount 和 DirectoryBackup 还需要镜像中的 sandbox-shim 辅助程序。有关 COPY 行，请参阅 @cloudflare/sandbox 要求。

此软件包不会向 Durable Object 存储写入任何内容。只有当你的类存储预览令牌、进程记录或快照 ID 时，这些数据才会存在。0.x 写入的键仍保留在存储中。软件包会忽略这些键，而你的类仍可读取它们，正如迁移预览 URL、隧道和出站规则的页面所示。

该包也不重试任何内容，也不设置时间限制。要停止运行过久的命令，请在 GNU coreutils timeout 下运行它，如 替换超时 所述。

• 从 Sandbox SDK 0.x 迁移
• API 对照
• Sandbox 生命周期
• Sandbox 安全