Back to Details

sandbox-migrate-to-next

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Migrate stable → Sandbox SDK 1.0 preview (
@next
)

从稳定版迁移至Sandbox SDK 1.0预览版（
@next
）

Perform the port. Follow the steps in order. Depth lives in docs—fetch the linked page when a step needs detail.
Human guide: Migrate · 1.0 preview
New projects should start on 
@next
(
sandbox-next
), not this skill. Day-to-day stable work → 
sandbox-stable
. Deprecated-API cleanup without moving to 
@next
→ 2026 deprecation guide first if needed.
Existing apps should migrate when you can, so you are ready when 1.0 becomes the stable release. Do not force production cutover without the user agreeing.
Prefer installed 
@next
types and the migrate doc over memory.
执行迁移操作。请按顺序遵循以下步骤。详细内容请查阅文档——若某步骤需要细节信息，请访问链接页面。
人工指南：迁移 · 1.0预览版
新项目应直接基于
@next
（
sandbox-next
）创建，无需使用本指南。日常稳定版开发请使用**
sandbox-stable
**。若仅需清理已废弃API但不迁移至
@next
，请先参考2026年废弃指南（如有需要）。
现有应用应在条件允许时进行迁移，以便在1.0版本成为稳定版时做好准备。未经用户同意，请勿强制切换至生产环境。
优先使用已安装的
@next
类型定义和迁移文档，而非依赖记忆。

Workflow

工作流程

  1. Review hard rules and the replacement map
  2. Audit the codebase; list hits and target shapes
  3. Clarify with the user (cutover, bridge, Python image, unclear sites)
  4. Upgrade package, image, and code
  5. Validate
Stop after any step that needs a user decision.
  1. 查阅硬性规则和替换映射表
  2. 审计代码库；列出需要修改的内容和目标形态
  3. 与用户确认（切换方案、桥接工具、Python镜像、不明确的站点）
  4. 升级包、镜像和代码
  5. 验证
若某步骤需要用户决策，请暂停操作等待确认。

Hard rules

硬性规则

  • Worker package and container image must be the same 
    @next
    line.
  • Production cutover uses immediate container rollout. Stable and 
    @next
    control protocols are incompatible both ways; gradual rollout leaves a broken mixed window. In-flight container work can stop.
  • After cutover, 
    await sandbox.exec(...)
    means process started, not command finished.
  • Argv is as-is (no implicit shell). Shell syntax needs an explicit shell binary.
  • Process handles have no stdin → terminals for interactive input.
  • Observation 
    timeout
    / 
    AbortSignal
    cancel the wait only, not the process.
  • No single retry loop for every error.
  • Do not invent APIs (
    gitCheckout
    on core, process stdin, string-exec completion helper).
  • Self-deployed bridge stays on stable (not part of the preview line yet).
  • Worker包和容器镜像必须使用同一版本线的
    @next
    。
  • 生产环境切换需使用立即容器滚动更新。稳定版与
    @next
    的控制协议双向不兼容；逐步滚动更新会导致混合状态下的功能异常。正在运行的容器任务可能会中断。
  • 切换后，
    await sandbox.exec(...)
    表示进程已启动，而非命令已完成。
  • 命令参数（Argv）保持原样（无隐式shell）。若需使用shell语法，需显式指定shell二进制文件。
  • 进程句柄无标准输入（stdin） → 需使用终端进行交互式输入。
  • 观测的
    timeout
    / 
    AbortSignal
    仅取消等待操作，不会终止进程。
  • 不要为所有错误设置统一的重试循环。
  • 不要自行发明API（如核心模块的
    gitCheckout
    、进程标准输入、字符串执行完成助手）。
  • 自部署的桥接工具需保留在稳定版（暂未纳入预览版线）。

Replacement map

替换映射表

Stable
@next
SANDBOX_TRANSPORT
/ 
transport
/ 
setTransport
Remove — RPC only
await sandbox.exec("cmd")
→ buffered result
await sandbox.exec(argv)
→ handle, then 
output
/ waits
execStream
/ 
startProcess
Same handle: 
logs
, 
waitFor*
, 
kill
Default / named sessionsGone — 
cwd
/
env
per launch, or one shell script
sandbox.terminal(request)
/ session terminal
createTerminal
+ 
terminal.connect(request)
xterm 
sessionId
terminalId
Interpreter methods on 
Sandbox
withInterpreter
→ 
sandbox.interpreter.*
gitCheckout
argv 
git
via 
exec
String kill signalsNumeric only
Files, mounts, backups, ports, tunnels, 
proxyToSandbox
Mostly unchanged (ignore session/transport bits on stable pages)
Depth: Migrate · after port, day-to-day → 
sandbox-next
稳定版
@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
调用
git
命令参数
字符串类型的终止信号仅支持数值类型
文件、挂载、备份、端口、隧道、
proxyToSandbox
基本不变（忽略稳定版文档中的会话/传输相关内容）
详细内容：迁移 · 迁移完成后，日常开发请使用**
sandbox-next
**

Audit

审计

sh
rg 'SANDBOX_TRANSPORT|transport:|setTransport|enableDefaultSession|createSession|getSession|deleteSession|execStream\(|startProcess\(|killProcess\(|sandbox\.terminal\(|sessionId|gitCheckout\(|SandboxTransport|ExecutionSession'
Also: string 
exec(
, 
cd
then a later 
exec
, bare 
createCodeContext
/ 
runCode
on 
Sandbox
.
sh
rg 'SANDBOX_TRANSPORT|transport:|setTransport|enableDefaultSession|createSession|getSession|deleteSession|execStream\\(|startProcess\\(|killProcess\\(|sandbox\\.terminal\\(|sessionId|gitCheckout\\(|SandboxTransport|ExecutionSession'
此外，还需检查：字符串形式的
exec(
、先执行
cd
再执行后续
exec
、
Sandbox
上直接调用
createCodeContext
/ 
runCode
的情况。

Clarify (ask when needed)

确认（必要时询问用户）

  • OK to cut production with 
    --containers-rollout=immediate
    (live processes/terminals/streams may stop)?
  • Self-deployed bridge? Leave on stable.
  • Python interpreter → 
    -python
     image variant?
  • Call sites not covered by the map?
  • 是否同意使用
    --containers-rollout=immediate
    切换至生产环境（正在运行的进程/终端/流可能会中断）？
  • 是否使用自部署的桥接工具？需保留在稳定版。
  • Python解释器是否需要使用**
    -python
    **镜像变体？
  • 是否存在未被映射表覆盖的调用场景？

Upgrade

升级

Package and image

包与镜像

sh
npm install @cloudflare/sandbox@next
dockerfile
FROM cloudflare/sandbox:next
sh
npm install @cloudflare/sandbox@next
dockerfile
FROM cloudflare/sandbox:next

Python: cloudflare/sandbox:next-python

Python版本：cloudflare/sandbox:next-python


Same prerelease tag on Worker and image when not on floating `next`.

若未使用浮动版本`next`，Worker和镜像需使用相同的预发布标签。

Code by area

分区域修改代码

Apply replacements from the map. For each area, implement from the doc—not from stable habits:
AreaDoc
Commands / handles / waitsProcesses · Processes API
cwd
/ 
env
/ secrets		Environment · Outbound traffic
Drop sessionsMigrate · Lifecycle
TerminalsTerminals
InterpreterInterpreter
ErrorsErrors
Durable job across requestsProcess execution — lifetime / durability
Commands (shape):
ts
// 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" });
ts
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
Terminals (shape):
ts
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 });
Interpreter (shape):
ts
import { Sandbox as BaseSandbox } from "@cloudflare/sandbox";
import { withInterpreter } from "@cloudflare/sandbox/interpreter";

export class Sandbox extends BaseSandbox<Env> {
  interpreter = withInterpreter(this);
}
Git (shape):
ts
const clone = await sandbox.exec(
  ["git", "clone", "--depth", "1", "--", repoUrl, "/workspace/repo"],
  { cwd: "/workspace" },
);
const result = await clone.output({ encoding: "utf8" });
Delete transport settings entirely. Remove session APIs. Isolate users with separate sandbox IDs.
根据映射表进行替换。针对每个功能区域，请依据文档实现——不要沿用稳定版的使用习惯：
功能区域文档链接
命令 / 句柄 / 等待进程 · 进程API
cwd
/ 
env
/ 密钥		环境 · 出站流量
移除会话迁移 · 生命周期
终端终端
解释器解释器
错误处理错误
请求间的持久化任务进程执行——生命周期/持久性
命令（代码形态）：
ts
// 之前（稳定版）
const result = await sandbox.exec("npm test");

// 之后（@next版）
const process = await sandbox.exec(["/bin/bash", "-lc", "npm test"]);
const result = await process.output({ encoding: "utf8" });
ts
const server = await sandbox.exec(["/bin/bash", "-lc", "npm run dev"], {
  cwd: "/workspace/app",
});
await server.waitForPort(3000, { timeout: 60_000 });
await server.kill(); // 数值类型；默认值15
终端（代码形态）：
ts
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 });
解释器（代码形态）：
ts
import { Sandbox as BaseSandbox } from "@cloudflare/sandbox";
import { withInterpreter } from "@cloudflare/sandbox/interpreter";

export class Sandbox extends BaseSandbox<Env> {
  interpreter = withInterpreter(this);
}
Git（代码形态）：
ts
const clone = await sandbox.exec(
  ["git", "clone", "--depth", "1", "--", repoUrl, "/workspace/repo"],
  { cwd: "/workspace" },
);
const result = await clone.output({ encoding: "utf8" });
完全删除传输设置。移除会话API。使用独立的sandbox ID隔离用户。

Deploy cutover

部署切换

Staging/branch first. Production is one deploy of matching Worker + image:
sh
npx wrangler deploy --containers-rollout=immediate
Leave 
rollout_active_grace_period
at default 
0
(or set 
0
if raised). After cutover, pre-deploy process/terminal IDs are invalid. Details: Migrate · Container rollouts
先在 staging 环境或分支上测试。生产环境需一次性部署匹配的Worker + 镜像：
sh
npx wrangler deploy --containers-rollout=immediate
保持
rollout_active_grace_period
默认值为
0
（若已修改则设为
0
）。切换后，部署前的进程/终端ID将失效。详细内容：迁移 · 容器滚动更新

Validate

验证

  1. Lockfile + Dockerfile on the same 
    @next
    line
  2. Typecheck against 
    @next
  3. Smoke argv 
    exec
    + 
    output({ encoding: "utf8" })
  4. Smoke long process / terminal / interpreter if used
  5. Errors distinguished: unavailable / interrupted-RPC / stale / local wait
  6. No live secrets in sandbox env
  7. Grep again for removed APIs
  8. Production used 
    --containers-rollout=immediate
Then day-to-day work uses 
sandbox-next
.
  1. 锁文件 + Dockerfile使用同一版本线的
    @next
  2. 基于
    @next
    进行类型检查
  3. 测试参数化
    exec
    + 
    output({ encoding: "utf8" })
  4. 若使用了长时进程/终端/解释器，进行冒烟测试
  5. 区分不同错误类型：不可用/RPC中断/过期/本地等待
  6. sandbox环境中无明文密钥
  7. 再次检查是否存在已移除的API
  8. 生产环境部署时使用了
    --containers-rollout=immediate
完成后，日常开发请使用**
sandbox-next
**。

Red flags — stop and fix

危险信号——立即停止并修复

  • Mixing 
    @next
    Worker with stable image (or reverse)
  • Gradual container rollout for this cutover
  • Treating 
    await exec
    as command completion
  • Assuming 
    cd
    / exports persist across 
    exec
    calls
  • One retry wrapper for every error
  • Inventing 
    gitCheckout
    , process stdin, or undocumented APIs
  • Keeping pre-cutover process/terminal IDs after deploy
  • Forcing production cutover without user agreement
  • Putting live secrets in 
    setEnvVars
    / launch 
    env
  • @next
    版Worker与稳定版镜像混用（反之亦然）
  • 本次切换使用逐步容器滚动更新
  • 将
    await exec
    视为命令完成
  • 假设
    cd
    / 环境变量在多次
    exec
    调用间持久化
  • 为所有错误设置统一的重试包装器
  • 自行实现
    gitCheckout
    、进程标准输入或未文档化的API
  • 部署后仍使用切换前的进程/终端ID
  • 未经用户同意强制切换至生产环境
  • 将明文密钥放入
    setEnvVars
    / 启动
    env
    中
    ",