Sandbox SDK — @next (1.0 預覽版)
在 Cloudflare Containers 上由 Workers 驅動的隔離 Linux 環境。
優先參考預覽文件與已安裝的 @next 類型定義，而非憑記憶。 API 會變動；此技能是閘門、合約與檢索地圖——並非完整手冊。
我們建議新專案使用此線路。仍使用預設套件的應用程式請參照 sandbox-stable。僅在要求時，透過 sandbox-migrate-to-next 進行移植。
1. 閘門 — 確認套件線路
在撰寫程式碼前，檢查應用程式：
| 檢查項目 | 必須符合 |
|---|---|
| npm 相依性 | @cloudflare/sandbox@next（或其他預覽標籤） |
| 容器映像檔 | 同一線路（例如 cloudflare/sandbox:next、next-python） |
| 若發現… | 動作 |
|---|---|
預設 @cloudflare/sandbox（無 @next） | 停止。 載入 sandbox-stable。不要使用此技能的 API。 |
使用者想要從 stable 移植到 @next | 停止。 載入 sandbox-migrate-to-next。 |
| 僅自行部署的 bridge | Bridge 尚未在 1.0 預覽線路上。將 bridge 保留在 stable 套件 + 映像檔上。Bridge (stable) |
切勿將 @next Worker 套件與 stable 容器映像檔混合（或反之亦然）。
技能安裝：Agent 設定 · cloudflare/skills
2. 合約 — 不可協商的條件
sandbox.exec(argv)接受一個 argv 列表，並在程序啟動時解析。它回傳一個 handle，而非完成的命令結果。- 使用 handle 方法收集結果：
output()、logs()、waitForExit()、waitForPort()、waitForLog()、kill(signal?)。 - 無隱含 shell。Shell 語法需要明確的 shell，例如
["/bin/bash", "-lc", script]。 - 每個啟動都是獨立的。一個
exec中的cd/export對下一個不可見。請為每個啟動傳遞cwd和env，或使用一個 shell 指令碼。 - Process handle 沒有 stdin。互動式使用請使用終端機（
createTerminal+connect）。 - 本機等待
timeout/AbortSignal僅取消等待。它們不會終止程序。請使用kill或exec的遠端timeout。 getProcess/listProcesses/getTerminal/listTerminals不會啟動容器；當沒有容器運行時，它們回傳null/[]。- Process 與 terminal ID 屬於目前的容器，而非永遠屬於某個 sandbox ID。對於必須在容器替換後仍持續的工作，請儲存完整的工作資訊（argv、cwd、env、應用程式狀態），而不僅僅是 ID。
- 僅在
setEnvVars/ 啟動env中放置非機密設定。即時憑證保留在 Worker 中；當 sandbox 呼叫外部 API 時，請使用出站處理器。 - 請勿發明已移除的穩定 API（核心上的
gitCheckout、字串exec完成、session 執行、sandbox.terminal(request)）。 - 請勿對每個錯誤使用一個重試迴圈（請參閱 Errors 文件）。
最小範例：
import { getSandbox, proxyToSandbox, Sandbox } from "@cloudflare/sandbox";
export { Sandbox };
const sandbox = getSandbox(env.Sandbox, "user-123");
const process = await sandbox.exec(["python3", "-c", "print(2 + 2)"]);
const result = await process.output({ encoding: "utf8" });
// result.stdout, result.exitCode
任務特定 API 文件：references/api-quick-ref.md
範例索引（next 分支）：references/examples.md
3. 檢索 — 開啟對應的文件
在實作前請先擷取頁面。已安裝的 @next 類型定義優於猜測。
| 你需要… | 開啟 |
|---|---|
| 方向確認/選擇預覽版 | 1.0 預覽版概覽 |
| 第一個 Worker、wrangler、Dockerfile | 開始使用 |
exec、handle、就緒狀態、永續性 | 程序執行 |
| Process API 簽章 | Processes API |
| Sandbox ID 與容器/休眠/銷毀的關係 | 生命週期 |
cwd / env / setEnvVars | 環境 |
| 互動式 PTY / 瀏覽器終端機 | 終端機 · Terminals API |
| Python/JS 程式碼直譯器 | 直譯器 · Interpreter API |
| 擴充功能模型 | 擴充功能 |
| 錯誤類別與復原 | 錯誤 · Errors API |
| 常見失敗 | 疑難排解 |
| API 中心 | API 參考 |
檔案、掛載、備份、連接埠、通道、proxyToSandbox | 共用表面的主要文件（忽略 stable-only 的 session/transport/sandbox.terminal）：檔案 · 儲存 / 掛載 · 連接埠 · 通道 · 備份 · 出站流量 · 暴露服務 · 生產環境 |
| 範例應用程式 | next 上的範例 |
| 仍在使用 stable 套件 | sandbox-stable · 主要 Sandbox 文件 |
| 移植現有的 stable 應用程式 | sandbox-migrate-to-next · 移植指南 |
4. 出貨前檢查
- Lockfile 與 Dockerfile 應使用相同的
@next線路 - 使用已安裝的
@next類型進行型別檢查 - 不要在 sandbox 環境中存放即時機密
- 當使用特定 URL 模式時，生產預覽主機名稱需要在自訂網域上設定萬用字元 DNS