sandbox-stable

Sandbox SDK — 稳定版软件包

在 Cloudflare Containers 上运行隔离的 Linux 环境，并由 Workers 驱动。

请优先参考 Sandbox 主文档和已安装的稳定版类型，而不是凭记忆作答。 此技能是一道门槛、一份约定和一张检索地图，而非完整手册。

这一行指的是当前稳定版的默认 npm 软件包。主 Sandbox 文档对此有说明。现有应用可以继续使用此版本并持续发布。

我们建议新项目使用 @cloudflare/sandbox@next 和 sandbox-next。在条件允许时，请使用 sandbox-migrate-to-next 规划迁移，以便在 1.0 成为稳定版时做好准备。除非用户提出要求，否则不要强行迁移。

1. 门槛 — 确认软件包版本线

编写代码前，先检查应用：

检查项	必须符合
npm 依赖	默认的 @cloudflare/sandbox（不是 @next / 预览标签）
容器镜像	对应的稳定版镜像（不是 cloudflare/sandbox:next）

如果发现……	操作
@cloudflare/sandbox@next 或 next 镜像	停止。 加载 sandbox-next。
用户希望迁移到 1.0 / @next	停止。 加载 sandbox-migrate-to-next。不要在稳定版软件包上半套用预览版 API。
只是清理已弃用的稳定版 API	留在此版本；使用 2026 弃用指南。这不代表迁移到 @next。

切勿混用稳定版 Worker 软件包和 @next 容器镜像（反之亦然）。

技能安装：Agent 设置 · cloudflare/skills

2. 约定 — 不可妥协的要求

• await sandbox.exec(command) 接受命令字符串，并在命令执行完毕后返回，其中包含缓冲后的 stdout / stderr / exitCode（以及相关字段）。
• 长时间运行和流式任务请使用稳定版命令 API（startProcess、execStream 及相关辅助工具），而不是 @next 的单句柄模型。请查阅 Commands 文档；不要在稳定版上臆造 @next 的 output() 句柄。
• 会话可以跨命令保留工作目录和环境（默认会话 / enableDefaultSession、createSession）。需要在多次调用间保留状态时，请参阅 Sessions 文档。
• 交互式浏览器终端通常使用稳定版的 sandbox.terminal(request) 和会话/xterm 辅助工具，而不是预览版的 createTerminal（除非软件包为 @next）。
• 使用隧道或大型/二进制流时，优先选择 RPC 传输。HTTP/WebSocket 传输已弃用（见下方清理指南）。
• 文件、挂载、端口、隧道、备份、生命周期和解释器的签名，请查阅主文档；以已安装的稳定版类型为准。
• 沙箱环境中放置非机密配置；实时凭据保存在 Worker 中。进程调用外部 API 时，请使用出站处理程序。
• 使用这些 URL 模式时，生产预览主机名需要在自定义域名上配置通配符 DNS。
• 依赖仍为稳定版时，不要应用 @next 的 argv/process.output() API。
• 自行部署的 bridge 继续使用稳定版软件包和镜像。Bridge

最小结构：

import { getSandbox, proxyToSandbox, Sandbox } from "@cloudflare/sandbox";

export { Sandbox };

const sandbox = getSandbox(env.Sandbox, "user-123");
const result = await sandbox.exec('python3 -c "print(2 + 2)"');
// result.stdout, result.exitCode, result.success

3. 检索 — 打开任务对应的文档

实现前先获取页面内容。已安装的稳定版类型优先于猜测。

你需要……	查看
了解概况	Sandbox 概览
第一个 Worker、模板、Docker	开始使用
exec、流式传输、后台进程	Commands API · 执行命令 · 后台进程 · 流式输出
跨命令的会话／Shell 状态	Sessions 概念 · Sessions API
getSandbox 选项、休眠、销毁	Lifecycle API · Sandbox 选项
环境变量	环境变量
文件	Files API · 管理文件 · 文件监视
存储桶／挂载	Storage API · 挂载存储桶
备份	Backups API · 备份与恢复
端口、预览 URL、公开访问	Ports API · 公开服务
隧道	Tunnels API
代理／Workers 连接	代理请求 · Workers 连接
浏览器／PTY 终端	Terminal API · Terminal 概念 · 浏览器终端
代码解释器	Interpreter API · 代码执行
在 Sandbox 中使用 Git	Git 工作流
密钥／出站流量	出站流量
WebSocket	WebSocket 连接
Docker-in-Docker	Docker in Docker
生产环境部署	生产环境部署
Containers 概念	Containers
操作指南索引	指南
API 索引	API 参考
在继续使用稳定版的同时了解弃用 API	2026 弃用指南
自行部署的桥接服务	Bridge · Bridge HTTP API
示例（稳定版／main）	GitHub 上的示例
在 1.0 预览版上开展新工作	sandbox-next · 1.0 预览版
将现有应用移植到 @next	sandbox-migrate-to-next · 迁移

废弃 API 清理（保持在稳定版）

先更新程序包和对应的映像，然后按照指南操作。典型的搜索方式：

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

此路径不会将你切换到 @next。

4. 发布前

• Worker 程序包和容器映像处于同一稳定版系列
• 使用已安装的稳定版类型进行类型检查
• 沙盒环境中没有真实密钥
• 如果使用了已废弃的传输方式或辅助工具，请完成或跟进 2026 年弃用项的清理工作
• 团队准备好使用 1.0 时，请使用 sandbox-migrate-to-next——不要在无人提示时强行切换