sandbox-next

Sandbox SDK — @next（1.0 预览版）

由 Workers 驱动的 Cloudflare Containers 隔离 Linux 环境。

请优先参考预览版文档和已安装的 @next 类型，不要依赖记忆。 API 会变化；此技能是准入门槛、契约和检索指南，并非完整手册。

我们建议新项目使用此版本线。仍在使用默认软件包的应用请使用 sandbox-stable。只有在用户要求时才通过 sandbox-migrate-to-next 进行迁移。

1. 准入检查 — 确认软件包版本线

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

检查项	必须匹配
npm 依赖项	@cloudflare/sandbox@next（或其他预览版标签）
容器映像	同一版本线（例如 cloudflare/sandbox:next、next-python）

如果发现……	操作
默认的 @cloudflare/sandbox（没有 @next）	停止。 加载 sandbox-stable。不要使用此技能中的 API。
用户想从 stable 迁移到 @next	停止。 加载 sandbox-migrate-to-next。
仅使用自部署的 bridge	Bridge 尚未进入 1.0 预览版。请让 bridge 继续使用 stable 软件包和映像。Bridge（stable）

绝不要混用 @next Worker 软件包与 stable 容器映像（或反过来）。

技能安装：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 时，请使用出站处理程序。
• 不要臆造已移除的 stable 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
Sandbox ID 与容器的区别，以及休眠 / 销毁	生命周期
cwd / env / setEnvVars	环境
交互式 PTY / 浏览器终端	终端 · 终端 API
Python/JS 代码解释器	解释器 · 解释器 API
扩展模型	扩展
错误类和恢复方法	错误 · 错误 API
常见故障	故障排除
API 总览	API 参考
文件、挂载、备份、端口、隧道、proxyToSandbox	共享功能请参阅主文档（忽略仅限 stable 的 session/transport/sandbox.terminal）：文件 · 存储 / 挂载 · 端口 · 隧道 · 备份 · 出站流量 · 公开服务 · 生产环境
示例应用	next 上的示例
仍在使用 stable 包	sandbox-stable · Sandbox 主文档
将现有 stable 应用移植到新版本	sandbox-migrate-to-next · 迁移

4. 发布前检查

• 锁文件和 Dockerfile 使用相同的 @next 版本线
• 根据已安装的 @next 类型进行类型检查
• Sandbox 环境中不得包含有效密钥
• 使用这些 URL 模式时，生产预览主机名需要在自定义域上配置通配符 DNS