用途:Cloudflare Sandbox SDK(@cloudflare/sandbox)用于在边缘的隔离 Ubuntu Linux 容器中运行代码,请求由 Durable Objects 按沙箱 ID 路由。状态为 Production Ready(Open Beta),最新版本 @cloudflare/sandbox@0.4.12,Docker 镜像 cloudflare/sandbox:0.4.12。
主要能力:三层架构——Worker 处理 HTTP 与 API 逻辑,Durable Object 按沙箱 ID 路由并保持持久身份,Ubuntu 容器提供完整 Linux 环境(Python 3.11、Node 20、Git 等,文件系统含 /workspace、/tmp、/home)。核心 API 包括 exec 执行命令、writeFile/readFile/mkdir/readdir/rm 文件操作、gitCheckout 克隆仓库、createCodeContext/runCode 代码解释器、spawn/isProcessRunning/killProcess 后台进程、createSession 会话管理、destroy 销毁沙箱。
使用方式:安装 npm install @cloudflare/sandbox@latest;在 wrangler.jsonc 中配置 compatibility_flags 为 nodejs_compat、containers、durable_objects 绑定与 migrations;Worker 中必须 export { Sandbox } from '@cloudflare/sandbox',用 getSandbox(env.Sandbox, 'id') 获取实例。首次请求创建容器约 2-3 分钟冷启动,后续请求小于 1 秒。多步工作流需用 createSession 创建会话并传入 exec,否则 cd 等状态不保留。
适用场景:交互式笔记本、IDE、持久工作区、一次性代码执行、CI/CD、测试、构建系统、数据管道、聊天式编码智能体、并行任务执行。
限制:容器默认临时,约 10 分钟空闲后所有文件、进程与状态被重置,重要数据需存 R2/KV/D1 等外部存储;本地开发需 Docker 运行;包版本与镜像版本需保持一致;需检查退出码、设置超时、清理临时沙箱,并避免将未净化的用户输入直接传给 exec 以防命令注入。部分细节资料暂未提供。