Sandbox 常见陷阱

# 陷阱与最佳实践 ## 常见错误 ### "容器无限运行" **原因:** 设置了 `keepAlive: true` 但未调用 `destroy()` **解决方案:** 使用 keepAlive 容器时，务必在完成后调用 `destroy()` typescript const sandbox = getSandbox(env.Sandbox, 'temp', { keepAlive: true }); try { const result = await sandbox.exec('python script.py'); return result.stdout; } finally { await sandbox.destroy(); // 必须调用以释放资源 } ### "CONTAINER_NOT_READY" **原因:** 容器仍在预配中（首次请求或休眠后） **解决方案:** 2-3 秒后重试 typescript async function execWithRetry(sandbox, cmd) { for (let i = 0; i setTimeout(r, 2000)); continue; } throw e; } } } ### "连接被拒绝：找不到容器端口" **原因:** Dockerfile 中缺少 `EXPOSE` 指令 **解决方案:** 在 Dockerfile 中添加 `EXPOSE `（仅 `wrangler dev` 需要，生产环境会自动暴露） ### "预览 URL 不工作" **原因:** 未配置自定义域名、缺少通配符 DNS、未设置 `normalizeId` 或未调用 `proxyToSandbox()` **解决方案:** 检查： 1. 是否配置了自定义域名？(非 `.workers.dev`) 2. 是否设置了通配符 DNS？(`*.domain.com → worker.domain.com`) 3. getSandbox 中是否设置了 `normalizeId: true`？ 4. fetch 中是否首先调用了 `proxyToSandbox()`？ ### "首次请求缓慢" **原因:** 冷启动（容器预配） **解决方案:** - 使用 `sleepAfter` 代替创建新沙箱 - 使用 cron 触发器进行预热 - 为关键沙箱设置 `keepAlive: true` ### "文件未持久化" **原因:** 文件位于 `/tmp` 或其他临时路径 **解决方案:** 使用 `/workspace` 存储持久化文件 ### "存储桶挂载在本地不工作" **原因:** 存储桶挂载需要 FUSE，`wrangler dev` 不支持 **解决方案:** 仅在生产环境测试存储桶挂载。本地使用模拟数据。 ### "不同的 normalizeId = 不同的沙箱" **原因:** 更改 `normalizeId` 选项会更改 Durable Object ID **解决方案:** 保持 `normalizeId` 设置一致。`normalizeId: true` 会将 ID 转为小写。 typescript // 这些会创建不同的沙箱: getSandbox(env.Sandbox, 'MyApp'); // DO ID: hash('MyApp') getSandbox(env.Sandbox, 'MyApp', { normalizeId: true }); // DO ID: hash('myapp') ### "代码上下文变量消失" **原因:** Con