Sandbox 生命周期

沙箱是代码运行的隔离执行环境。每个沙箱：

具有唯一标识符（sandbox ID）
包含隔离的文件系统
在专用 Linux container 中运行
在 container 活跃时保持状态
作为 Cloudflare Durable Object 存在

生命周期状态

创建

首次引用其 ID 时会创建沙箱：

const sandbox = getSandbox(env.Sandbox, "user-123");
await sandbox.exec('echo "Hello"'); // First request creates sandbox

活跃

沙箱 container 正在运行并处理请求。所有状态保持可用：文件、正在运行的进程、shell 会话和环境变量。

空闲

在一段时间无活动后（默认 10 分钟，可通过 sleepAfter 配置），container 会停止以释放资源。当下一个请求到达时，会启动一个全新的 container。所有先前状态都会丢失，环境重置为初始状态。

注意：具有 keepAlive: true 的 container 永远不会进入空闲状态。它们每 30 秒自动发送心跳 ping 以防止被逐出。

销毁

沙箱会被显式销毁或自动清理：

await sandbox.destroy();
// All files, processes, and state deleted permanently

Container 生命周期与状态

沙箱状态仅在 container 活跃时存在。理解这一点对于构建可靠应用至关重要。

当 container 活跃时（通常是几分钟到几小时的活动）：

写入 /workspace、/tmp、/home 的文件保持可用
后台进程继续运行
shell 会话保持其工作目录和环境
代码解释器上下文保留变量和导入

当 container 停止时（由于无活动或显式销毁）：

所有文件被删除
所有进程终止
所有 shell 状态重置
所有代码解释器上下文被清除

下一个请求会创建一个具有干净环境的新 container。

命名策略

按用户沙箱

const sandbox = getSandbox(env.Sandbox, `user-${userId}`);

将此模式用于交互式环境、playground 和 notebook，其中每个用户都会返回自己的活跃工作区。

按会话沙箱

const sessionId = `session-${Date.now()}-${Math.random()}`;
const sandbox = getSandbox(env.Sandbox, sessionId);
// Later:
await sandbox.destroy();

将此模式用于需要干净环境的一次性执行、CI/CD 和测试。

按任务沙箱

const sandbox = getSandbox(env.Sandbox, `build-${repoName}-${commit}`);

幂等操作，具有清晰的任务到沙箱映射。适用于构建、流水线和后台作业。

请求路由

对沙箱的第一个请求决定其地理位置。后续请求会路由到同一位置。

对于全球应用：

选项 1：每个用户多个沙箱，带区域后缀（user-123-us、user-123-eu）
选项 2：每个用户单个沙箱（更简单，但部分用户可能看到更高延迟）

生命周期管理

何时销毁

try {
	const sandbox = getSandbox(env.Sandbox, sessionId);
	await sandbox.exec("npm run build");
} finally {
	await sandbox.destroy(); // Clean up temporary sandboxes
}

应销毁：会话结束、任务完成、不再需要资源

不要销毁：个人环境、长时间运行的服务

管理 keepAlive container

具有 keepAlive: true 的 container 需要显式管理，因为它们不会自动超时：

const sandbox = getSandbox(env.Sandbox, 'persistent-task', {
  keepAlive: true
});

// Later, when done with long-running work
await sandbox.setKeepAlive(false); // Allow normal timeout behavior
// Or explicitly destroy:
await sandbox.destroy();

处理 container 重启

container 会在无活动或故障后重启。设计应用以处理状态丢失：

// Check if required files exist before using them
const files = await sandbox.listFiles("/workspace");
if (!files.includes("data.json")) {
	// Reinitialize: container restarted and lost previous state
	await sandbox.writeFile("/workspace/data.json", initialData);
}

await sandbox.exec("python process.py");

版本兼容性

SDK 会自动检查 npm 包版本是否与 Docker container 镜像版本匹配。版本不匹配可能导致功能中断或行为异常。

会发生什么：

在沙箱启动时，SDK 会查询 container 的版本
如果版本不匹配，会记录警告
若版本不兼容，某些功能可能无法正常工作

何时可能看到警告：

你更新了 npm 包（npm install @cloudflare/sandbox@latest），但忘记更新 Dockerfile 中的 FROM 行

如何修复：将 Dockerfile 更新为匹配你的 npm 包版本。例如，如果使用 @cloudflare/[email protected]：

# Default image (JavaScript/TypeScript)
FROM docker.io/cloudflare/sandbox:0.7.0

# Or Python image if you need Python support
FROM docker.io/cloudflare/sandbox:0.7.0-python

有关镜像变体和扩展基础镜像的详情，请参阅 Dockerfile 参考。

最佳实践

命名一致 - 使用清晰、可预测的命名方案
清理临时沙箱 - 完成后始终销毁
复用用户工作区 - 每个用户一个长期沙箱通常足够
批量操作 - 组合命令：npm install && npm test && npm build
按短暂状态设计 - container 会在无活动后重启，丢失所有状态