sandbox-migrate-to-next

将 stable 迁移到 Sandbox SDK 1.0 预览版（@next）

执行迁移。按顺序完成以下步骤。详细内容请参阅文档——需要某一步的详细信息时，获取对应链接页面。

面向开发者的指南：迁移 · 1.0 预览版

新项目应从 @next（sandbox-next）开始，而不是使用此技能。日常 stable 开发 → sandbox-stable。如果要清理已弃用的 API，但不迁移到 @next，请先视需要参阅2026 弃用指南。

现有应用应尽可能迁移，以便在 1.0 成为稳定版时做好准备。未经用户同意，不要强行切换生产环境。

优先参考已安装的 @next 类型和迁移文档，而不是依赖记忆。

工作流

1. 查看硬性规则和替换对照表
2. 审查代码库；列出命中项和目标形式
3. 与用户确认（切换、桥接、Python 镜像、含义不明的代码位置）
4. 升级软件包、镜像和代码
5. 验证

任何步骤需要用户作出决定时，都应停止。

硬性规则

• Worker 软件包和容器镜像必须使用同一条 @next 版本线。
• 生产环境切换必须使用立即容器滚动更新。Stable 和 @next 的控制协议双向不兼容；渐进式滚动更新会导致新旧版本混用期间出现故障。运行中的容器任务可能会停止。
• 切换后，await sandbox.exec(...) 表示进程已启动，不表示命令已完成。
• 参数数组会原样传递（不会隐式调用 shell）。Shell 语法需要显式指定 shell 二进制文件。
• 进程句柄不支持 stdin → 交互式输入请使用终端。
• 观察操作的 timeout / AbortSignal 只会取消等待，不会取消进程。
• 不要对所有错误都使用同一个重试循环。
• 不要臆造 API（例如 core 上的 gitCheckout、进程 stdin、字符串形式的 exec 完成辅助方法）。
• 自行部署的桥接服务继续使用 stable（尚未纳入预览版版本线）。

替换对照表

Stable	@next
SANDBOX_TRANSPORT / transport / setTransport	移除——仅支持 RPC
await sandbox.exec("cmd") → 缓冲结果	await sandbox.exec(argv) → 句柄，然后使用 output / 等待方法
execStream / startProcess	同一类句柄：logs、waitFor*、kill
默认 / 命名会话	已移除——每次启动时通过 cwd/env 设置，或使用一个 shell 脚本
sandbox.terminal(request) / 会话终端	createTerminal + terminal.connect(request)
xterm sessionId	terminalId
Sandbox 上的解释器方法	withInterpreter → sandbox.interpreter.*
gitCheckout	通过 exec 调用 argv git
字符串形式的终止信号	仅支持数字
文件、挂载、备份、端口、隧道、proxyToSandbox	基本不变（stable 页面中与会话/传输相关的内容除外）

详细内容：迁移 · 迁移后，日常开发请使用 → sandbox-next

审查

rg 'SANDBOX_TRANSPORT|transport:|setTransport|enableDefaultSession|createSession|getSession|deleteSession|execStream\(|startProcess\(|killProcess\(|sandbox\.terminal\(|sessionId|gitCheckout\(|SandboxTransport|ExecutionSession'

还需检查：字符串形式的 exec(、先执行 cd 后又调用 exec 的情况，以及直接在 Sandbox 上调用 createCodeContext / runCode 的情况。

确认（需要时询问）

• 是否可以通过 --containers-rollout=immediate 切换生产环境（正在运行的进程/终端/流可能会停止）？
• 是否为自行部署的桥接服务？保持使用 stable。
• Python 解释器是否需要使用 -python 镜像变体？
• 是否有未被替换对照表涵盖的调用位置？

升级

软件包和镜像

npm install @cloudflare/sandbox@next

FROM cloudflare/sandbox:next
# Python: cloudflare/sandbox:next-python

未使用浮动的 next 时，Worker 和镜像必须使用相同的预发布标签。

按区域编写代码

根据映射应用替换。对于每个区域，请依据文档实现，而不是沿用惯常做法：

区域	文档
命令 / 句柄 / 等待	进程 · 进程 API
cwd / env / 密钥	环境 · 出站流量
删除会话	迁移 · 生命周期
终端	终端
解释器	解释器
错误	错误
跨请求的持久作业	进程执行 — 生命周期 / 持久性

命令（形式）：

// Before (stable)
const result = await sandbox.exec("npm test");

// After (@next)
const process = await sandbox.exec(["/bin/bash", "-lc", "npm test"]);
const result = await process.output({ encoding: "utf8" });

const server = await sandbox.exec(["/bin/bash", "-lc", "npm run dev"], {
  cwd: "/workspace/app",
});
await server.waitForPort(3000, { timeout: 60_000 });
await server.kill(); // numeric; default 15

终端（形式）：

const terminal = await sandbox.createTerminal({ command: ["bash"], cwd: "/workspace" });
const t = await sandbox.getTerminal(terminal.id);
if (!t) return new Response("terminal gone", { status: 410 });
return t.connect(request, { cursor, cols, rows });

解释器（形式）：

import { Sandbox as BaseSandbox } from "@cloudflare/sandbox";
import { withInterpreter } from "@cloudflare/sandbox/interpreter";

export class Sandbox extends BaseSandbox<Env> {
  interpreter = withInterpreter(this);
}

Git（形式）：

const clone = await sandbox.exec(
  ["git", "clone", "--depth", "1", "--", repoUrl, "/workspace/repo"],
  { cwd: "/workspace" },
);
const result = await clone.output({ encoding: "utf8" });

彻底删除传输设置。移除会话 API。使用独立的沙盒 ID隔离用户。

部署切换

先在预发布环境 / 分支进行。生产环境只部署一次相匹配的 Worker 和镜像：

npx wrangler deploy --containers-rollout=immediate

将 rollout_active_grace_period 保持为默认值 0（如果调高过，则设回 0）。切换后，部署前的进程 / 终端 ID 将失效。详情：迁移 · 容器滚动发布

验证

1. 锁文件和 Dockerfile 使用相同的 @next 版本线
2. 针对 @next 进行类型检查
3. 冒烟测试 argv exec + output({ encoding: "utf8" })
4. 如果使用，则对长时间运行的进程 / 终端 / 解释器进行冒烟测试
5. 区分错误：不可用 / RPC 中断 / 过期 / 本地等待
6. 沙盒环境变量中不包含实时密钥
7. 再次搜索已移除的 API
8. 生产环境使用了 --containers-rollout=immediate

之后，日常工作使用 sandbox-next。

危险信号 — 停止并修复

• 将使用 @next 的 Worker 与稳定版镜像混用（或反过来）
• 此次切换使用渐进式容器滚动发布
• 将 await exec 视为命令已完成
• 假设 cd / 导出变量会在多次 exec 调用之间保持
• 所有错误都使用同一个重试封装
• 臆造 gitCheckout、进程 stdin 或未记录的 API
• 部署后仍保留切换前的进程 / 终端 ID
• 未经用户同意强行切换生产环境
• 在 setEnvVars / 启动 env 中放入实时密钥