用途:在 Cloudflare Containers 上运行隔离 Linux 环境,由 Workers 驱动,本技能针对当前稳定默认 npm 包 @cloudflare/sandbox,帮助构建或修改 Sandbox 应用。
主要能力与约定:await sandbox.exec(command) 接收命令字符串,命令结束后返回缓冲的 stdout、stderr、exitCode 等;长时与流式任务使用稳定版命令 API(startProcess、execStream 等),不要套用 @next 的单句柄模型。会话可跨命令保留工作目录与环境(默认会话、enableDefaultSession、createSession)。交互式浏览器终端常用 sandbox.terminal(request) 与会话/xterm 辅助。使用隧道或大/二进制流时优先 RPC 传输,HTTP/WebSocket 传输已弃用。文件、挂载、端口、隧道、备份、生命周期、解释器等以主文档签名为准,并信任已安装的稳定类型。非机密配置放 sandbox env,实时凭据放 Worker;进程调用外部 API 时用 outbound handlers。生产预览主机名在相应 URL 模式下需自定义域名的通配 DNS。
使用方式:先确认包线——npm 依赖应为默认 @cloudflare/sandbox(非 @next/preview),容器镜像也须匹配稳定版,不可混用稳定 Worker 包与 @next 镜像。若发现 @next 或 next 镜像,应停止并改用 sandbox-next;若要迁移到 1.0/@next,应改用 sandbox-migrate-to-next,不要在稳定包上部分套用预览 API;仅清理已弃用稳定 API 时留在本技能,参考 2026 弃用指南。最小形态示例: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)"'); 结果含 stdout、exitCode、success。实现前先查对应文档页,已安装稳定类型优先于猜测。
适用场景:在稳定包上开发或维护 Sandbox 应用、清理弃用 API、自部署 bridge。限制:不适用于 @next/1.0 预览开发或迁移;不要强制用户迁移;未提供具体收费、价格与效果信息。