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 辅助函数——除非包是@next，否则不要使用预览的createTerminal。 - 在使用隧道或大型/二进制流式处理时，优先选择 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 · 代码执行 |
| 沙箱中的 Git | Git 工作流 |
| 密钥 / 出口流量 | 出站流量 |
| WebSocket | WebSocket 连接 |
| Docker-in-Docker | Docker in Docker |
| 生产部署 | 生产部署 |
| Containers 概念 | Containers |
| 操作指南索引 | 指南 |
| API 索引 | API 参考 |
| 仍在稳定包上清理已弃用的 API | 2026 弃用指南 |
| 自部署 bridge | 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——不要未经提示强制切换