Sandbox SDK — @next (1.0 预览版)
在 Cloudflare Containers 上运行的隔离 Linux 环境，由 Workers 驱动。
优先使用预览文档和已安装的 @next 类型，而非记忆。 API 会变化；此技能是一个门控、一份合约以及一张检索地图——而不是完整手册。
我们建议 新项目 使用此版本。仍使用默认包的应用请用 sandbox-stable。仅在收到明确指令时，通过 sandbox-migrate-to-next 进行移植。
1. 门控 — 确认包线
在编写代码前，请检查应用：
| 检查项 | 必须匹配 |
|---|---|
| npm 依赖 | @cloudflare/sandbox@next（或其他预览标签） |
| 容器镜像 | 同一行（如 cloudflare/sandbox:next、next-python） |
| 如果发现… | 操作 |
|---|---|
默认 @cloudflare/sandbox（无 @next） | 停止。 加载 sandbox-stable。不要应用此技能的 API。 |
用户希望从稳定版移植到 @next | 停止。 加载 sandbox-migrate-to-next。 |
| 仅自部署的 bridge | Bridge 尚未 在 1.0 预览版线上。请将 bridge 保留在稳定版包和镜像上。Bridge（稳定版） |
切勿将 @next 的 Worker 包与稳定版的容器镜像混合使用（反之亦然）。
技能安装：Agent 设置 · cloudflare/skills
2. 合约 — 不可妥协的规则
sandbox.exec(argv)接受一个 argv 列表，并在进程 启动 时解析。它返回一个 句柄，而非命令的最终结果。- 通过句柄方法收集结果：
output()、logs()、waitForExit()、waitForPort()、waitForLog()、kill(signal?)。 - 无隐式 shell。Shell 语法需要显式指定 shell，例如
["/bin/bash", "-lc", script]。 - 每次启动相互独立。一次
exec中的cd/export对下一次不可见。请每次启动时传递cwd和env，或者使用单个 shell 脚本。 - 进程句柄 没有标准输入。交互式使用 → 终端（
createTerminal+connect）。 - 本地等待的
timeout/AbortSignal仅取消 等待操作。它们不会终止进程。请使用kill或exec的远程timeout。 getProcess/listProcesses/getTerminal/listTerminals不会 启动容器；当没有活动容器时返回null/[]。- 进程和终端 ID 属于 当前容器，而非永久与某个沙箱 ID 绑定。对于需要持久化的工作，请存储完整的任务（argv、cwd、env、应用状态）——而不仅仅是 ID。
- 仅在
setEnvVars/ 启动env中放置非机密配置。实时凭据保留在 Worker 中；当沙箱调用外部 API 时使用出站处理程序。 - 不要 创造已移除的稳定版 API（核心上的
gitCheckout、字符串式exec完成、会话执行、sandbox.terminal(request)）。 - 不要 对每个错误都使用一个重试循环（参见错误文档）。
最小示例：
import { getSandbox, proxyToSandbox, Sandbox } from "@cloudflare/sandbox";
export { Sandbox };
const sandbox = getSandbox(env.Sandbox, "user-123");
const process = await sandbox.exec(["python3", "-c", "print(2 + 2)"]);
const result = await process.output({ encoding: "utf8" });
// result.stdout, result.exitCode
任务特定的 API 文档：references/api-quick-ref.md
示例索引（next 分支）：references/examples.md
3. 检索 — 为任务打开文档
在实现之前获取页面。已安装的 @next 类型优先于猜测。
| 你需要… | 打开 |
|---|---|
| 定位/选择预览版 | 1.0 预览版概述 |
| 第一个 Worker、wrangler、Dockerfile | 开始使用 |
exec、句柄、就绪性、持久性 | 进程执行 |
| 进程 API 签名 | 进程 API |
| 沙箱 ID vs 容器 vs 休眠/销毁 | 生命周期 |
cwd / env / setEnvVars | 环境 |
| 交互式 PTY / 浏览器终端 | 终端 · 终端 API |
| Python/JS 代码解释器 | 解释器 · 解释器 API |
| 扩展模型 | 扩展 |
| 错误类与恢复 | 错误 · 错误 API |
| 常见故障 | 故障排除 |
| API 中心 | API 参考 |
文件、挂载、备份、端口、隧道、proxyToSandbox | 共享区域的主文档（忽略仅稳定版的 session/transport/sandbox.terminal）：文件 · 存储/挂载 · 端口 · 隧道 · 备份 · 出站流量 · 暴露服务 · 生产部署 |
| 示例应用 | next 上的示例 |
| 仍在使用稳定版包 | sandbox-stable · Sandbox 主文档 |
| 移植现有稳定版应用 | sandbox-migrate-to-next · 迁移指南 |
4. 发布前检查
- 锁文件与 Dockerfile 在同一
@next线上 - 使用已安装的
@next类型进行类型检查 - 沙箱环境中不含实时机密信息
- 使用自定义域名的生产预览主机名需要通配符 DNS（如果使用此类 URL 模式）