從穩定版遷移至 Sandbox SDK 1.0 預覽版 (@next)
執行移植作業。請按順序執行步驟。詳細資訊請查閱文件——當某個步驟需要細節時，請擷取連結的頁面。
新專案應從 @next（sandbox-next）開始，而不是使用此技能。日常穩定版開發 → 請使用 sandbox-stable。如需清理已棄用的 API 但不要遷移到 @next → 請先參考 2026 年棄用指南。
現有應用應在你方便時進行遷移，以便在 1.0 成為穩定版本時準備就緒。未經使用者同意，請勿強制進行生產環境的切換。
優先使用已安裝的 @next 型別和遷移文件，而不是依賴記憶。
工作流程
- 檢閱硬性規則和替換對照表
- 審計程式碼庫；列出比對到的項目和目標寫法
- 與使用者確認（關於切換、橋接、Python 映像檔、不明確的站點）
- 升級套件、映像檔和程式碼
- 驗證
若某個步驟需要使用者決定，請停止該步驟。
硬性規則
- Worker 套件和容器映像檔必須是相同的
@next版本。 - 生產環境切換使用立即容器部署。穩定版和
@next的控制協定是互不相容的；逐步部署會產生一個有問題的混合視窗。正在進行的容器工作可能會停止。 - 切換後，
await sandbox.exec(...)表示行程已啟動，而非命令已完成。 - 參數列表保持原樣（沒有隱含的 shell）。Shell 語法需要明確的 shell 二進制檔案。
- 行程控制代碼沒有標準輸入 → 用於互動式輸入的終端機。
- 觀測
timeout/AbortSignal僅取消等待，而非取消行程。 - 不要為所有錯誤使用單一重試迴圈。
- 不要發明 API（例如核心上的
gitCheckout、行程標準輸入、字串執行的完成輔助函式）。 - 自行部署的橋接保持在穩定版（目前不屬於預覽版的一部分）。
替換對照表
| 穩定版 | @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 |
| 字串 kill 訊號 | 僅限數值 |
檔案、掛載、備份、連接埠、隧道、proxyToSandbox | 大部分保持不變（忽略穩定版頁面上的會話/傳輸部分） |
詳細資訊：遷移指南 · 移植後，日常開發 → 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進行生產環境切換嗎？（執行中的行程/終端機/串流可能會停止） - 有自行部署的橋接嗎？請保留在穩定版。
- Python 直譯器 → 使用
-python映像檔變體？ - 有未被對照表涵蓋的調用點嗎？
升級
套件和映像檔
npm install @cloudflare/sandbox@next
FROM cloudflare/sandbox:next
# Python：cloudflare/sandbox:next-python
當不使用浮動的 next 時，Worker 和映像檔使用相同的預發佈標籤。
按區域修改程式碼
套用對照表中的替換。對於每個區域，根據文件實作——而不是根據穩定版的習慣：
| 區域 | 文件 |
|---|---|
| 命令 / 控制代碼 / 等待 | 行程 · 行程 API |
cwd / env / 秘密 | 環境 · 對外流量 |
| 移除會話 | 遷移指南 · 生命週期 |
| 終端機 | 終端機 |
| 直譯器 | 直譯器 |
| 錯誤 | 錯誤 |
| 跨請求的持久性工作 | 行程執行 — 生命週期 / 持久性 |
命令（寫法）：
// 之前（穩定版）
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" });
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
終端機（寫法）：
const terminal = await sandbox.createTerminal({ command: ["bash"], cwd: "/workspace" });
const t = await sandbox.getTerminal(terminal.id);
if (!t) return new Response("終端機已消失", { 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。使用不同的 sandbox ID 來隔離使用者。
部署切換
先在暫存/分支環境進行。生產環境是一次部署匹配的 Worker 和映像檔：
npx wrangler deploy --containers-rollout=immediate
將 rollout_active_grace_period 保留為預設值 0（如果已提高則設為 0）。切換後，預先部署的行程/終端機 ID 將失效。詳細資訊：遷移指南 · 容器部署
驗證
- Lockfile 和 Dockerfile 使用相同的
@next版本 - 根據
@next進行型別檢查 - 測試 argv
exec+output({ encoding: "utf8" }) - 如果使用，測試長時間運行的行程 / 終端機 / 直譯器
- 區分錯誤類型：不可用 / RPC 中斷 / 過時 / 本地等待
- Sandbox 環境中沒有即時的秘密
- 再次搜尋已移除的 API
- 生產環境使用了
--containers-rollout=immediate
然後，日常開發使用 sandbox-next。
紅旗——請停止並修正
- 將
@nextWorker 與穩定版映像檔混合使用（或反過來） - 對此切換使用逐步容器部署
- 將
await exec視為命令完成 - 假設
cd/ exports 會在多次exec呼叫之間保留 - 為所有錯誤使用單一重試包裝器
- 發明
gitCheckout、行程標準輸入或未記載的 API - 部署後保留切換前的行程/終端機 ID
- 未經使用者同意強制進行生產環境切換
- 將即時秘密放入
setEnvVars/ 啟動env中