关于 sandbox-sdk
sandbox-sdk 是一项技能，介绍如何在 Cloudflare Workers 上使用 Cloudflare Sandbox SDK 构建隔离的代码执行环境。内容涵盖命令执行、代码解释、文件操作、沙箱生命周期和端口公开。
主要功能
- 01执行 Shell 命令
- 02运行 Python、JavaScript 和 TypeScript
- 03持久化解释器上下文
- 04沙箱文件操作
- 05端口公开与资源清理
适用场景
- 01在沙箱中运行大模型生成的代码
- 02执行脚本及构建或测试命令
- 03使用持久化解释器状态分析数据
- 04预览沙箱中的 HTTP 服务
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/sandbox-sdk确认已加载。
附带文件references/api-quick-ref.mdreferences/examples.md
详细介绍
Cloudflare Sandbox SDK
在 Cloudflare Workers 上构建安全、隔离的代码执行环境。
首先：验证安装
npm install @cloudflare/sandbox
docker info # Must succeed - Docker required for local dev
检索资源
你对 Sandbox SDK 的了解可能已经过时。处理任何 Sandbox SDK 任务时，优先检索，而非依赖预训练知识。
实现功能时，请先获取相关文档页面或示例。
必需配置
wrangler.jsonc（必须完全一致——请勿修改结构）：
{
"containers": [{
"class_name": "Sandbox",
"image": "./Dockerfile",
"instance_type": "lite",
"max_instances": 1
}],
"durable_objects": {
"bindings": [{ "class_name": "Sandbox", "name": "Sandbox" }]
},
"migrations": [{ "new_sqlite_classes": ["Sandbox"], "tag": "v1" }]
}
Worker 入口——必须重新导出 Sandbox 类：
import { getSandbox } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox'; // Required export
快速参考
| 任务 | 方法 |
|---|---|
| 获取沙箱 | getSandbox(env.Sandbox, 'user-123') |
| 运行命令 | await sandbox.exec('python script.py') |
| 运行代码（解释器） | await sandbox.runCode(code, { language: 'python' }) |
| 写入文件 | await sandbox.writeFile('/workspace/app.py', content) |
| 读取文件 | await sandbox.readFile('/workspace/app.py') |
| 创建目录 | await sandbox.mkdir('/workspace/src', { recursive: true }) |
| 列出文件 | await sandbox.listFiles('/workspace') |
| 暴露端口 | await sandbox.exposePort(8080) |
| 销毁 | await sandbox.destroy() |
核心模式
执行命令
const sandbox = getSandbox(env.Sandbox, 'user-123');
const result = await sandbox.exec('python --version');
// result: { stdout, stderr, exitCode, success }
代码解释器（推荐用于 AI）
使用 runCode() 执行大模型生成的代码，并获取丰富的输出：
const ctx = await sandbox.createCodeContext({ language: 'python' });
await sandbox.runCode('import pandas as pd; data = [1,2,3]', { context: ctx });
const result = await sandbox.runCode('sum(data)', { context: ctx });
// result.results[0].text = "6"
语言：python、javascript、typescript
状态会在上下文中持久保留。生产环境中请创建显式上下文。
文件操作
await sandbox.mkdir('/workspace/project', { recursive: true });
await sandbox.writeFile('/workspace/project/main.py', code);
const file = await sandbox.readFile('/workspace/project/main.py');
const files = await sandbox.listFiles('/workspace/project');
如何选择
| 需求 | 使用 | 原因 |
|---|---|---|
| Shell 命令、脚本 | exec() | 直接控制、支持流式处理 |
| 大模型生成的代码 | runCode() | 输出丰富、状态持久保留 |
| 构建/测试流水线 | exec() | 退出码、捕获 stderr |
| 数据分析 | runCode() | 图表、表格、pandas |
扩展 Dockerfile
基础镜像（docker.io/cloudflare/sandbox:0.7.0）包含 Python 3.11、Node.js 20 和常用工具。
通过扩展 Dockerfile 添加依赖：
FROM docker.io/cloudflare/sandbox:0.7.0
# Python packages
RUN pip install requests beautifulsoup4
# Node packages (global)
RUN npm install -g typescript
# System packages
RUN apt-get update && apt-get install -y ffmpeg && rm -rf /var/lib/apt/lists/*
EXPOSE 8080 # Required for local dev port exposure
保持镜像精简——这会影响冷启动时间。
预览 URL（端口暴露）
暴露在沙箱中运行的 HTTP 服务：
const { url } = await sandbox.exposePort(8080);
// Returns preview URL for the service
生产环境要求：预览 URL 需要使用自定义域名，并配置通配符 DNS（*.yourdomain.com）。.workers.dev 域名不支持预览 URL 子域名。
参见：https://developers.cloudflare.com/sandbox/guides/expose-services/
OpenAI Agents SDK 集成
SDK 在 @cloudflare/sandbox/openai 提供 OpenAI Agents 助手：
import { Shell, Editor } from '@cloudflare/sandbox/openai';
完整集成模式请参见 examples/openai-agents。
沙箱生命周期
getSandbox()会立即返回——容器会在首次操作时延迟启动- 容器在闲置 10 分钟后进入休眠状态（可通过
sleepAfter配置） - 使用
destroy()立即释放资源 - 相同的
sandboxId始终返回同一个沙箱实例
反模式
- 不要使用内部客户端（
CommandClient、FileClient）——请使用sandbox.*方法 - 不要跳过 Sandbox 导出——缺少
export { Sandbox }时 Worker 无法部署 - 多用户场景不要硬编码沙箱 ID——请使用用户/会话标识符
- 不要忘记清理——临时沙箱请调用
destroy()
详细参考
- references/api-quick-ref.md——包含选项和返回类型的完整 API
- references/examples.md——包含使用场景的示例索引