用途
本技能面向在 Cloudflare 上构建或维护 Sandbox 应用的开发者，基于稳定的 @cloudflare/sandbox npm 包。Sandbox 提供运行在 Cloudflare Containers 上的隔离 Linux 环境，由 Workers 驱动。该技能本身定位为一道“闸门”、一份“契约”和一张“检索地图”，而非完整手册；实现前应优先查阅官方 Sandbox 文档和已安装的稳定类型定义。
主要能力
- 版本闸门：在编写代码前检查应用的 npm 依赖是否为默认的 @cloudflare/sandbox（而非 @next 或预览标签），容器镜像是否匹配稳定镜像（而非 cloudflare/sandbox:next）。若发现 @next 包或 next 镜像，应停止并改用 sandbox-next；若用户希望迁移到 1.0 / @next，应改用 sandbox-migrate-to-next，不要在稳定包上部分套用预览 API。仅清理已弃用的稳定 API 时仍留在本技能，参考 2026 弃用指南。禁止将稳定 Worker 包与 @next 容器镜像混用（反之亦然）。
- 稳定 API 契约：await sandbox.exec(command) 接收命令字符串，命令结束时解析，返回缓冲的 stdout / stderr / exitCode 及相关字段。长时间运行和流式任务使用稳定命令 API（startProcess、execStream 及相关辅助函数），而非 @next 的单句柄模型。会话可跨命令保留工作目录和环境（默认会话 / enableDefaultSession、createSession）。交互式浏览器终端通常使用 sandbox.terminal(request) 及 session/xterm 辅助函数。使用隧道或大型/二进制流时优先使用 RPC 传输，HTTP/WebSocket 传输已弃用。文件、挂载、端口、隧道、备份、生命周期和解释器请查阅主文档获取签名，并信任已安装的稳定类型。非机密配置放在 sandbox 环境变量中，实时凭据放在 Worker 中；进程调用外部 API 时使用出站处理器。使用相关 URL 模式时，生产预览主机名需要在自定义域名上配置通配符 DNS。依赖仍为稳定版时，不要套用 @next 的 argv/process.output() API。自部署桥接保持使用稳定包和镜像。
- 文档检索：按任务类型提供对应文档入口，包括 Sandbox 概览、快速开始、Commands API、Sessions、生命周期、环境变量、文件、存储与挂载、备份、端口、隧道、代理与 Workers 连接、终端、代码解释器、Git 工作流、出站流量、WebSocket、Docker-in-Docker、生产部署、容器概念、指南、API 参考、2026 弃用指南、桥接、GitHub 示例，以及 sandbox-next 和 sandbox-migrate-to-next。
使用方式
最小代码形态：
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
技能安装：Agent setup · cloudflare/skills。
弃用 API 清理（仍留在稳定版）：先更新包和匹配镜像，再遵循指南。典型搜索：
rg 'SANDBOX_TRANSPORT|transport:|exposePort\(|enableDefaultSession|execStream\(|readFileStream|writeFileStream'
此路径不会切换到 @next。
适用场景
适用于在稳定 @cloudflare/sandbox 包上构建或维护 Sandbox 应用、清理已弃用的稳定 API、以及需要按任务检索官方文档的场景。新项目建议使用 @cloudflare/sandbox@next 配合 sandbox-next；当团队准备好迁移到 1.0 时，使用 sandbox-migrate-to-next，不要未经用户要求强制切换。
限制
本技能不是完整手册，实现前必须查阅对应文档页面，已安装的稳定类型优先于猜测。不得在稳定包上套用 @next API，不得混用稳定 Worker 包与 @next 容器镜像。关于具体收费、价格、平台支持范围等信息，资料中暂未提供。