# Cloudflare 沙箱 SDK **状态**：生产就绪（开放测试版） **最后更新**：2025-10-29 **依赖项**：`cloudflare-worker-base`、`cloudflare-durable-objects`（建议理解） **最新版本**：`@cloudflare/sandbox@0.4.12`，Docker 映像：`cloudflare/sandbox:0.4.12` ** ** ## 快速入门（15 分钟） ### 1\.安装 SDK 并设置 Wrangler npm install @cloudflare/sandbox@latest **牧马人.jsonc：** { “名称”：“我的沙箱工人”， "main": "src/index.ts", “compatibility_flags”：[“nodejs_compat”]， “容器”：[{ "class_name": "沙箱", “图像”：“cloudflare/sandbox：0.4.12”， “instance_type”：“精简版” }], “耐用对象”：{ “绑定”：[{ "class_name": "沙箱", “名称”：“沙盒” }] }, “迁移”：[{ “标签”：“v1”， “new_sqlite_classes”：[“沙箱”] }] } **为什么这很重要：** * `nodejs_compat` 启用 SDK 所需的 Node.js API * `containers` 定义 Ubuntu 容器镜像 * `durable_objects` 绑定支持持久路由 * `migrations` 注册 Sandbox 类 ### 2\.创建您的第一个沙箱工作人员从 '@cloudflare/sandbox' 导入 { getSandbox, type Sandbox }; 从“@cloudflare/sandbox”导出{Sandbox}；类型环境 = { 沙箱：DurableObjectNamespace； }; 导出默认值{ 异步获取（请求：请求，环境：环境）：Promise { // 获取沙箱实例（如果不存在则创建） const sandbox = getSandbox(env.Sandbox, 'my-first-sandbox'); // 执行Python代码 const result = wait sandbox.exec('python3 -c "print(2 + 2)"'); 返回 Response.json({ 输出：结果.stdout，成功：结果.成功， exitCode: 结果.exitCode }); } }; **关键：** * **必须从 Worker 中的“@cloudflare/sandbox”导出**“{ Sandbox }” * 沙箱ID决定路由（相同ID=相同容器） * 第一个请求创建容器（~2-3 分钟冷启动） * 后续请求很快（<1s） ### 3\.部署和测试 npm 运行部署卷曲 https://your-worker.workers.dev 预期输出： { “输出”：“4\n”， “成功”：真实， “退出代码”：0 } ** ** ## 架构（了解三层模型） ### 沙箱如何工作 ┌──────────────────────────────────────────┐ │ 你的工人（第 1 层） │ │ - 处理 HTTP 请求 │ │ - 调用 getSandbox() │ │ - 使用 sandbox.exec()、writeFile() 等 │ └──────────────┬──────────────────────────┘ │ 通过持久对象的 RPC ┌──────────────▼──────────────────────────┐ │ 耐用对象（第 2 层） │ │ - 通过沙箱 ID 进行路由 │ │ - 保持持久身份 │ │ - 地理粘性 │ └──────────────┬──────────────────────────┘ │ 容器API ┌──────────────▼──────────────────────────┐ │ Ubuntu 容器（第 3 层） │ │ - 完整的 Linux 环境 │ │ - Python 3.11、Node 20、Git 等 │ │ - 文件系统：/workspace、/tmp、/home │ │ - 进程隔离（基于虚拟机） │ └──────────────────────────────────────────┘ **关键见解**：工作人员处理 API 逻辑（快速），持久对象路由请求（持久身份），容器执行代码（完整功能）。 ** ** ## 关键容器生命周期（最重要的部分！） ### 容器状态 ┌──────────┐ 第一次请求 ┌────────┐ ~10 分钟空闲 ┌──────┐ │ 不 │ ────────────────>│ 活动 │ ──────────────> │ 空闲 │ │ 创建 │ │ │ │ │ └──────────┘ └────┬────┘ └──┬────┘ │ ^ │ │ │ 新要求 │ │ └──────────────────────┘ │ │ ▼ ▼ 文件保留所有文件已删除进程运行所有进程被杀死状态保持全部状态重置 ### #1 陷阱：默认情况下是短暂的 **当容器处于活动状态时**（上次请求后约 10 分钟）： * ✅ `/workspace`、`/tmp`、`/home` 中的文件保留 * ✅ 后台进程继续运行 * ✅ Shell 环境变量保留 * ✅ 保留会话工作目录 **当容器空闲时**（不活动后）： * ❌ **所有文件已删除**（整个文件系统重置） * ❌ **所有进程终止** * ❌ **所有 shell 状态丢失** * ⚠️ 下一个请求从头开始创建**新容器** **这不像传统服务器**。沙箱的设计是短暂的。 ### 处理持久性 **对于重要数据**：使用外部存储 // 在容器空闲之前保存到R2 等待 sandbox.writeFile('/workspace/data.txt', content); const fileData =等待 sandbox.readFile('/workspace/data.txt'); 等待 env.R2.put('备份/data.txt', fileData); // 下次请求时恢复 const 恢复=等待 env.R2.get('backup/data.txt'); 如果（恢复）{ 等待 sandbox.writeFile('/workspace/data.txt', 等待恢复.text()); } **对于构建工件**：接受短暂性或使用缓存 // 检查是否需要设置（处理冷启动） const存在=等待sandbox.readdir('/workspace/project').catch(() => null); 如果（！存在）{ 等待 sandbox.gitCheckout(repoUrl, '/workspace/project'); 等待 sandbox.exec('npm install', { cwd: '/workspace/project' }); } // 现在可以安全地运行构建了等待 sandbox.exec('npm run build', { cwd: '/workspace/project' }); ** ** ## 会话管理（聊天代理的游戏规则改变者） ### 什么是会话？会话是一个沙箱内的 **bash shell 上下文**。想想终端选项卡。 **关键属性**： * 每个会话都有独立的工作目录 * 会话共享相同的文件系统 * 工作目录在同一会话中跨命令持续存在 * 非常适合多步骤工作流程 ### 模式：基于聊天的编码代理类型对话状态 = { 沙盒ID：字符串；会话 ID：字符串； }; // 第一条消息：创建沙箱和会话 const sandboxId = `用户-${userId}`; const sandbox = getSandbox(env.Sandbox, sandboxId); const sessionId =等待 sandbox.createSession(); // 存储在会话状态（数据库、KV等）等待 env.KV.put(`对话：${conversationId}`, JSON.stringify({ 沙盒ID, 会话ID })); // 稍后的消息：重用相同的会话 const state = wait env.KV.get(`对话:${conversationId}`); const { sandboxId, sessionId } = JSON.parse(state); const sandbox = getSandbox(env.Sandbox, sandboxId); // 命令在相同的上下文中运行等待 sandbox.exec('cd /workspace/project', { session: sessionId }); 等待 sandbox.exec('ls -la', { session: sessionId }); // 仍在 /workspace/project 中等待 sandbox.exec('git status', { session: sessionId }); // 仍在 /workspace/project 中 ### 没有会话（常见错误） // ❌ 错误：每个命令在单独的会话中运行等待 sandbox.exec('cd /workspace/project'); 等待 sandbox.exec('ls'); // 不在 /workspace/project 中（不同的会话） ### 模式：并行执行 const session1 = 等待 sandbox.createSession(); const session2 = 等待 sandbox.createSession(); // 同时运行不同的任务等待 Promise.all([ sandbox.exec('python train_model.py', { session: session1 }), sandbox.exec('节点generate_reports.js', { session: session2 }) ]); ** ** ## 沙箱命名策略 ### 每用户沙箱（持久工作区） const sandbox = getSandbox(env.Sandbox, `user-${userId}`); **优点**：用户的工作在积极使用时仍然存在（10 分钟空闲时间） **缺点**：地理锁定（第一个请求确定位置） **用例**：交互式笔记本、IDE、持久工作区 ### 每会话沙箱（每次都是新鲜的） const sandboxId = `session-${Date.now()}-${crypto.randomUUID()}`; const sandbox = getSandbox(env.Sandbox, sandboxId); // 使用后总是销毁等待 sandbox.destroy(); **优点**：干净的环境，无状态污染 **缺点**：请求之间没有持久性 **用例**：一次性代码执行、CI/CD、测试 ### 每任务沙箱（幂等且可追踪） const sandbox = getSandbox(env.Sandbox, `build-${repoName}-${commitSha}`); **优点**：可重现、可调试、可缓存 **缺点**：需要明确的清理策略 **用例**：构建系统、数据管道、自动化工作流程 ** ** ## 核心API参考 ### 获取沙箱从 '@cloudflare/sandbox' 导入 { getSandbox }； const sandbox = getSandbox(env.Sandbox, 'unique-sandbox-id'); // 如果不存在则创建新的沙箱，或者获取现有的沙箱 ### 执行命令 // 基本执行 const result = wait sandbox.exec('python3 script.py'); console.log(结果.stdout); // 标准输出 console.log(结果.stderr); // 标准错误 console.log(结果.exitCode); // 退出代码（0 = 成功） console.log(结果.成功); // 布尔值 (退出代码 === 0) // 带选项 const 结果 =等待 sandbox.exec('npm install', { cwd: '/workspace/project', // 工作目录 timeout: 120000, // 超时时间（默认值：30 秒） session: sessionId, // 会话 ID env: { NODE_ENV: '生产' } // 环境变量 }); // 始终检查退出代码！如果（！结果。成功）{ 抛出新错误(`命令失败：${result.stderr}`); } ### 文件操作 // 写入文件等待 sandbox.writeFile('/workspace/data.txt', '内容'); // 读取文件 const content = wait sandbox.readFile('/workspace/data.txt'); // 创建目录等待 sandbox.mkdir('/workspace/project', { recursive: true }); // 列出目录 const 文件 =等待 sandbox.readdir('/workspace'); 控制台.log(文件); // ['data.txt', '项目'] // 删除文件/目录等待 sandbox.rm('/workspace/data.txt'); 等待 sandbox.rm('/workspace/project', { recursive: true }); ### Git 操作 // 克隆存储库（已优化，比 exec('git clone') 更快）等待 sandbox.gitCheckout( 'https://github.com/user/repo', '/工作区/回购' ）； // 现在使用标准 git 命令等待 sandbox.exec('git status', { cwd: '/workspace/repo' }); 等待 sandbox.exec('git diff', { cwd: '/workspace/repo' }); ### 代码解释器（类似 Jupyter） // 创建Python上下文 const ctx = wait sandbox.createCodeContext({ language: 'python' }); // 执行代码 - 自动返回最后一个表达式 const 结果 = 等待 sandbox.runCode(` 将 pandas 导入为 pd df = pd.DataFrame({'a': [1, 2, 3], 'b': [4, 5, 6]}) df['a'].sum() # 这个值是自动返回的 `, { 上下文: ctx }); console.log(结果.结果[0].文本); //“6” console.log(结果.logs); // print() 语句的输出 console.log(结果.错误); // 任何错误 ### 后台进程 // 启动长时间运行的进程 const proc = wait sandbox.spawn('python server.py'); console.log(proc.pid); // 检查是否仍在运行 const running = wait sandbox.isProcessRunning(proc.pid); // 杀死进程等待 sandbox.killProcess(proc.pid); ### 清理 // 永久销毁沙箱等待 sandbox.destroy(); // 所有文件被删除，容器被删除，无法恢复 ** ** ## 关键规则 ### 总是这样做 ✅ **检查退出代码** \- `if (!result.success) {处理错误}` ✅ **使用会话进行多步骤工作流程** \- 保留工作目录 ✅ **处理冷启动** \- 在假设文件存在之前检查文件是否存在 ✅ **设置超时** \- 防止长时间操作挂起 ✅ **销毁临时沙箱** \- 清理基于临时/会话的沙箱 ✅ **使用外部存储持久性** \- R2/KV/D1 用于重要数据 ✅ **验证用户输入** \- 在 exec() 之前进行清理以防止命令注入 ✅ **导出 Sandbox 类** \- `从 '@cloudflare/sandbox' 导出 { Sandbox }` ### 永远不要这样做 ❌ **假设文件在空闲后仍然存在** \- 容器在约 10 分钟后重置 ❌ **忽略退出代码** \- 始终检查 `result.success` 或 `result.exitCode` ❌ **没有会话的链命令** \- `cd /dir` 则 `ls` 将不起作用 ❌ **执行未经处理的用户输入** \- 使用代码解释器或彻底验证 ❌ **忘记 nodejs_compat flag** \- 在 wrangler.jsonc 中必需 ❌ **跳过迁移** \- 持久对象需要迁移条目 ❌ **使用 .workers.dev 作为预览 URL** \- 需要自定义域 ❌ **创建无限沙箱** \- 销毁临时沙箱以避免泄漏 ** ** ## 已知问题预防此技能可防止 **10** 已记录的问题： ### 问题#1：缺少nodejs_compat 标志 **错误**：`ReferenceError：未定义 fetch` 或 `缓冲区未定义` **来源**： **为什么会发生**：SDK 需要标准 Workers 中不可用的 Node.js API **预防**：将 `"compatibility_flags": ["nodejs_compat"]` 添加到 wrangler.jsonc ### 问题#2：缺少迁移 **错误**：`错误：找不到“沙盒”类` **来源**： **为什么会发生**：必须通过迁移注册持久对象 **预防**：在 wrangler.jsonc 中包含迁移数组 ### 问题 #3：假设文件持久性 **错误**：文件在不活动后消失 **来源**： **为什么会发生**：容器在约 10 分钟后空闲，所有状态重置 **预防**：使用外部存储 (R2/KV) 或检查每个请求是否存在 ### 问题#4：会话目录混乱 **错误**：命令在错误的目录中执行 **来源**： **为什么会发生**：除非明确指定，否则每个 exec() 都会使用新会话 **预防**：使用 `createSession()` 创建会话，传递给所有相关命令 ### 问题#5：忽略退出代码 **错误**：假设命令在失败时成功 **来源**：Shell 最佳实践 **为什么会发生**：不检查 `result.success` 或 `result.exitCode` **预防**：始终检查：`if (!result.success) throw new Error(result.stderr)` ### 问题#6：不处理冷启动 **错误**：命令失败，因为未安装依赖项 **来源**： **为什么发生**：容器在空闲期后重置 **预防**：在运行命令之前检查是否需要设置 ### 问题 #7：Docker 未运行（本地开发） **错误**：本地开发期间“无法构建容器” **来源**： **为什么发生**：本地开发需要 Docker 守护进程 **预防**：确保 Docker Desktop 在“npm run dev”之前运行 ### 问题 #8：版本不匹配（包与 Docker 映像） **错误**：API 方法不可用或行为异常 **来源**：GitHub 问题 **为什么会发生**：npm 软件包版本与 Docker 镜像版本不匹配 **预防**：保持 `@cloudflare/sandbox` 软件包和 `cloudflare/sandbox` 镜像同步 ### 问题#9：不清理临时沙箱 **错误**：资源耗尽，意外成本 **来源**：资源管理最佳实践 **为什么会发生**：创建沙箱而不销毁它们 **预防**：临时沙箱的finally块中的`await sandbox.destroy()` ### 问题#10：命令注入漏洞 **错误**：未经净化的用户输入造成的安全漏洞 **来源**：安全最佳实践 **为什么会发生**：将用户输入直接传递给 `exec()` **预防**：使用代码解释器 API 或彻底验证/净化输入 ** ** ## 配置文件参考 ### wrangler.jsonc（完整示例） { “名称”：“我的沙盒应用程序”， "main": "src/index.ts", “兼容性日期”：“2025-10-29”， “compatibility_flags”：[“nodejs_compat”]， “容器”：[{ "class_name": "沙箱", “图像”：“cloudflare/sandbox：0.4.12”， “instance_type”：“精简版” }], “耐用对象”：{ “绑定”：[{ "class_name": "沙箱", “名称”：“沙盒” }] }, “迁移”：[{ “标签”：“v1”， “new_sqlite_classes”：[“沙箱”] }], “环境”：{ “ANTHROPIC_API_KEY”：{ "description": "可选：用于 AI 功能" } }, “可观察性”：{ “启用”：真 } } **为什么要进行这些设置：** * `nodejs_compat`：SDK 工作所需 * `containers.image`: 特定版本保证一致性 * `instance_type: "lite"`：最小实例，升级到“large”以获得更多资源 * `migrations`：注册沙箱持久对象类 * `observability`：启用日志记录以进行调试 ### Dockerfile（可选 - 对于本地开发）仅在扩展基础镜像时才需要：来自cloudflare/沙盒：0.4.12 # 安装附加工具运行 apt-get update && apt-get install -y \ ffmpeg\ 图像魔法\ && rm -rf /var/lib/apt/lists/* # 公开预览 URL 的端口（仅限本地开发）曝光8080 ** ** ## 常见模式 ### 模式 1：一次性代码执行导出默认值{ 异步获取（请求：请求，环境：环境）{ const { 代码, 语言 } = wait request.json(); // 创建临时沙箱 const sandboxId = `exec-${Date.now()}-${crypto.randomUUID()}`; const sandbox = getSandbox(env.Sandbox, sandboxId); 尝试{ // 创建代码上下文 const ctx =等待 sandbox.createCodeContext({ 语言 }); // 安全地执行代码 const 结果 = 等待 sandbox.runCode(code, { 上下文：ctx，超时：10000 }); 返回 Response.json({ 结果：结果.结果？.[0]？.文本，日志：结果.logs，错误：结果.错误 }); }最后{ // 始终清理等待 sandbox.destroy(); } } }; **何时使用**：用于代码执行、代码游乐场、学习平台的 API 端点 ### 模式 2：持久用户工作区导出默认值{ 异步获取（请求：请求，环境：环境）{ const userId = request.headers.get('X-User-ID'); const { 命令，sessionId：existingSession } =等待request.json(); // 用户特定的沙箱（活动时持续存在） const sandbox = getSandbox(env.Sandbox, `user-${userId}`); // 获取或创建会话让 sessionId = 现有会话； if (!sessionId) { sessionId =等待sandbox.createSession(); } // 在持久上下文中执行命令 const 结果 = 等待 sandbox.exec(命令, { 会话：会话 ID，超时：30000 }); 返回 Response.json({ sessionId, // 返回下次请求输出：结果.stdout，错误：结果.stderr，成功：结果.成功 }); } }; **何时使用**：交互式编码环境、笔记本、IDE、开发工作区 ### 模式 3：CI/CD 构建管道异步函数 runBuild(repoUrl: string, commit: string, env: Env) { const sandboxId = `build-${repoUrl.split('/').pop()}-${commit}`; const sandbox = getSandbox(env.Sandbox, sandboxId); 尝试{ // 克隆存储库等待 sandbox.gitCheckout(repoUrl, '/workspace/repo'); // 签出具体提交等待 sandbox.exec(`git checkout ${commit}`, { cwd: '/工作区/repo' }); // 安装依赖项 const install = wait sandbox.exec('npm install', { cwd: '/工作区/repo', 超时: 180000 // 3 分钟 }); 如果（！安装.成功）{ 抛出新错误（`安装失败：${install.stderr}`）； } // 运行构建 const build = wait sandbox.exec('npm run build', { cwd: '/工作区/repo', 超时: 300000 // 5 分钟 }); 如果（！build.success）{ 抛出新错误(`构建失败：${build.stderr}`); } // 将工件保存到 R2 const dist =等待 sandbox.exec('tar -czf dist.tar.gz dist', { cwd: '/工作区/repo' }); const artifact = wait sandbox.readFile('/workspace/repo/dist.tar.gz'); 等待 env.R2.put(`builds/${commit}.tar.gz`, 工件); 返回 { success: true, artifactKey: `builds/${commit}.tar.gz` }; }最后{ // 可选：保留沙箱用于调试或销毁 // 等待 sandbox.destroy(); } } **何时使用**：构建系统、测试管道、部署自动化 ### 模式 4：带有 Claude 代码的 AI 代理异步函数 runClaudeCodeOnRepo( 回购网址：字符串，任务：字符串，环境：环境 ): Promise<{ diff: 字符串;日志：字符串}> { const sandboxId = `claude-${Date.now()}`; const sandbox = getSandbox(env.Sandbox, sandboxId); 尝试{ // 克隆存储库等待 sandbox.gitCheckout(repoUrl, '/workspace/repo'); // 通过安全环境注入运行 Claude Code CLI // ⚠️ 安全：使用 env 选项而不是 shell 导出来防止日志中的密钥暴露 const 结果 = 等待 sandbox.exec( `claude -p "${task}" --权限模式acceptEdits`, { cwd: '/工作区/repo', 超时: 300000, // 5 分钟环境：{ ANTHROPIC_API_KEY：环境ANTHROPIC_API_KEY } } ）； // 获取变化的差异 const diff =等待 sandbox.exec('git diff', { cwd: '/工作区/repo' }); 返回{ 差异：差异.stdout，日志：结果.stdout }; }最后{ 等待 sandbox.destroy(); } } **何时使用**：自动代码重构、代码生成、人工智能驱动的开发 ** ** ## 使用捆绑资源 ### 脚本（脚本/） * `setup-sandbox-binding.sh` \- 交互式 wrangler.jsonc 配置 * `test-sandbox.ts` \- 测试沙箱设置的验证脚本 **用法示例：** # 设置牧马人配置 ./scripts/setup-sandbox-binding.sh # 测试沙箱 npx tsx 脚本/test-sandbox.ts ### 参考文献（参考文献/） * `references/persistence-guide.md` \- 深入探讨容器生命周期和持久性 * `references/session-management.md` \- 高级会话模式和最佳实践 * `references/common-errors.md` \- 完整的错误列表及解决方案 * `references/naming-strategies.md` \- 为不同的用例选择沙箱 ID **当克劳德应该加载这些**时： * 在调试状态问题或冷启动时加载 `persistence-guide.md` * 在构建多步骤工作流程或聊天代理时加载“session-management.md” * 遇到特定错误时加载 `common-errors.md` * 设计沙箱架构时加载`naming-strategies.md` ** ** ## 高级主题 ### 地理分布对沙箱 ID 的第一个请求确定其地理位置（通过持久对象）。 **对于全球应用程序**： // 选项 1：每个用户多个沙箱（更好的延迟） const 区域 = request.cf?.colo || '默认'; const sandbox = getSandbox(env.Sandbox, `user-${userId}-${region}`); // 选项 2：单一沙箱（对于远程用户来说更简单、延迟更高） const sandbox = getSandbox(env.Sandbox, `user-${userId}`); ### 错误处理策略异步函数 safeSandboxExec( 沙箱：沙箱， cmd：字符串，选项？：任何）{ 尝试{ const 结果 = 等待 sandbox.exec(cmd, { ...选项，超时：选项？.timeout || 30000 }); 如果（！结果。成功）{ console.error(`命令失败：${cmd}`, { 退出代码：结果.退出代码， stderr: 结果.stderr }); 返回{ 成功：假，错误：结果.stderr， exitCode: 结果.exitCode }; } 返回{ 成功：真实，输出：结果.stdout，退出代码：0 }; } 捕获（错误）{ console.error(`沙箱错误：`, error); 返回{ 成功：假，错误：错误消息，退出代码：-1 }; } } ### 安全强化 // 输入验证函数 sanitizeCommand(输入：字符串): 字符串 { const 危险 = ['rm -rf', '$(', '`', '&&', '||', ';', '|']; for (危险的常量模式) { if (input.includes(pattern)) { throw new Error(`检测到危险模式：${pattern}`); } } 返回输入； } // 对于不受信任的代码使用代码解释器而不是直接执行异步函数executeUntrustedCode（代码：字符串，沙箱：沙箱）{ const ctx = wait sandbox.createCodeContext({ language: 'python' }); 返回等待 sandbox.runCode(code, { context: ctx, timeout: 10000 }); } ** ** ## 依赖关系 **必填**： * `@cloudflare/sandbox@0.4.12` \- 沙箱 SDK * `wrangler@latest` \- 部署 CLI * Docker Desktop - 仅限本地开发 **可选**： * `@anthropic-ai/sdk` \- 用于 AI 功能 * `@cloudflare/workers-types` \- TypeScript 类型 ** ** ## 官方文档 * **Cloudflare 沙箱** ： * **架构指南**： * **API 参考**： * **持久对象**： * **GitHub SDK**： ** ** ## 软件包版本（2025-10-29 验证） { “依赖项”：{ “@cloudflare/sandbox”：“^0.4.12” }, “开发依赖项”：{ "牧马人": "^3.80.0", “@cloudflare/workers-types”：“^4.20241106.0” } } **Docker 镜像**：`cloudflare/sandbox:0.4.12` ** ** ## 制作示例该技能基于Cloudflare官方教程： * **克劳德代码集成**： * **AI 代码执行器** : * **构建时间**：约 15 分钟（设置）+ 约 5 分钟（首次部署） * **错误**：0（已阻止所有 10 个已知问题） * **验证**：✅ 使用 Python、Node.js、Git、后台进程、会话进行测试 ** ** ## 故障排除 ### 问题：“未找到‘Sandbox’类” **解决方案**：将迁移添加到 wrangler.jsonc 并确保 Worker 中的 `export { Sandbox }` ### 问题：文件在一段时间后消失 **解决方案**：容器在大约 10 分钟后空闲。使用R2/KV进行持久化或重建环境 ### 问题：命令在错误的目录中执行 **解决方案**：使用`createSession()`创建会话，将sessionId传递给所有相关命令 ### 问题：本地开发期间出现 Docker 错误 **解决方案**：确保 Docker Desktop 在 `npm run dev` 之前运行 ### 问题：“fetch 未定义” **解决方案**：将 `"compatibility_flags": ["nodejs_compat"]` 添加到 wrangler.jsonc ** ** ## 完整设置清单 * `npm install @cloudflare/sandbox@latest` * 添加`nodejs_compat`到compatibility_flags * 添加具有正确镜像版本的容器配置 * 添加持久对象绑定 * 添加沙箱类的迁移 * 在 Worker 中导出 Sandbox 类： `export { Sandbox } from '@cloudflare/sandbox'` * Docker 桌面运行（仅限本地开发） * 使用简单的exec命令进行测试 * 验证正在检查退出代码 * 实现临时沙箱的清理 * 测试冷启动行为 ** ** **有问题吗？有问题吗？** 1.具体错误解决方案查看`references/common-errors.md` 2.验证wrangler.jsonc配置中的所有步骤 3.查看官方文档： 4. 确保 Docker 正在运行以进行本地开发 5.确认软件包版本与Docker镜像版本匹配

Cloudflare 沙箱

包含技能