安定版 → Sandbox SDK 1.0 プレビュー (@next) への移行
移行を実行します。 手順は順番に従ってください。詳細はドキュメントにあります。手順で詳細が必要な場合は、リンク先のページを参照してください。
新しいプロジェクト は @next (sandbox-next) で開始し、このスキルは使用しません。 日々の安定版作業 → sandbox-stable。非推奨APIのクリーンアップを @next に移行せずに行う場合は、必要に応じてまず 2026年非推奨ガイド を参照してください。
既存のアプリは、1.0 が安定版リリースになったときに備えて、可能なときに移行してください。ユーザーの同意なしに本番環境の切り替えを強制しないでください。
インストール済みの @next の型と移行ドキュメントをメモリより優先してください。
ワークフロー
- 確認 ハードルールと置換マップ
- 監査 コードベース、ヒットとターゲット形状をリストアップ
- 確認 ユーザーと相談（切り替え、ブリッジ、 Python イメージ、不明確なサイト）
- アップグレード パッケージ、イメージ、コード
- 検証
ユーザーの判断が必要なステップの後は停止します。
ハードルール
- Worker パッケージとコンテナイメージは 同じ
@nextラインである必要があります。 - 本番環境の切り替えは 即時 コンテナロールアウトを使用します。安定版と
@nextの制御プロトコルは互換性がなく、段階的ロールアウトは壊れた混合ウィンドウを残します。進行中のコンテナ作業は停止する可能性があります。 - 切り替え後、
await sandbox.exec(...)はプロセスが 開始 したことを意味し、コマンドが 終了 したことは意味しません。 - 引数 (argv) はそのままです（暗黙のシェルはありません）。シェル構文には明示的なシェルバイナリが必要です。
- プロセスハンドルには stdin がありません → インタラクティブ入力のための端末。
- 観測 (Observation) の
timeout/AbortSignalは 待機のみ をキャンセルし、プロセスはキャンセルしません。 - すべてのエラーに対して単一のリトライループはありません。
- API をでっち上げないでください（コア上の
gitCheckout、プロセス stdin、文字列実行完了ヘルパー）。 - 自己デプロイのブリッジは 安定版 のままにします（まだプレビューラインの一部ではありません）。
置換マップ
| 安定版 | @next |
|---|---|
SANDBOX_TRANSPORT / transport / setTransport | 削除 — RPC のみ |
await sandbox.exec("cmd") → バッファリングされた結果 | await sandbox.exec(argv) → ハンドル、その後 output / 待機 |
execStream / startProcess | 同じハンドル: logs、waitFor*、kill |
| デフォルト / 名前付きセッション | 削除 — cwd/env は起動ごと、または1つのシェルスクリプト |
sandbox.terminal(request) / セッション端末 | createTerminal + terminal.connect(request) |
xterm の sessionId | terminalId |
Sandbox のインタプリタメソッド | withInterpreter → sandbox.interpreter.* |
gitCheckout | exec 経由の 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を削除します。別々のサンドボックスIDでユーザーを分離します。
デプロイ切り替え
最初にステージング/ブランチ。本番環境は、一致する Worker + イメージの 1回 のデプロイです:
npx wrangler deploy --containers-rollout=immediate
rollout_active_grace_period はデフォルトの 0 のままにします（または引き上げられている場合は 0 に設定します）。切り替え後、デプロイ前のプロセス/端末IDは無効になります。詳細: 移行 · コンテナロールアウト
検証
- ロックファイル + Dockerfile が同じ
@nextラインにあること @nextに対して型チェック- 引数
exec+output({ encoding: "utf8" })のスモークテスト - 使用されている場合、長時間プロセス / 端末 / インタプリタのスモークテスト
- エラーの区別: 利用不可 / 中断RPC / 古い / ローカル待機
- サンドボックス環境にライブシークレットがないこと
- 削除されたAPIをもう一度grep
- 本番環境で
--containers-rollout=immediateが使用されたこと
その後、日々の作業では sandbox-next を使用します。
レッドフラグ — 停止して修正
@nextWorker と安定版イメージの混在（またはその逆）- この切り替えでの段階的コンテナロールアウト
await execをコマンド完了として扱うことcd/ エクスポートがexec呼び出し間で永続化すると仮定すること- すべてのエラーに対する1つのリトライラッパー
gitCheckout、プロセス stdin、または文書化されていないAPIをでっち上げること- デプロイ後の切り替え前のプロセス/端末IDを保持すること
- ユーザーの同意なしに本番環境の切り替えを強制すること
- ライブシークレットを
setEnvVars/ 起動envに配置すること