Sandbox SDK — 穩定套件
在 Cloudflare Containers 上執行的隔離 Linux 環境，由 Workers 驅動。
優先參考主要 Sandbox 文件以及已安裝的穩定型別，而非依賴記憶。 此技能是一個閘道、一份合約，以及一張檢索地圖，而非完整的手冊。
此行是目前穩定的預設 npm 套件。主要 Sandbox 文件 對此有詳細說明。現有的應用程式可以繼續留在這裡並持續發布。
我們建議新的專案使用 @cloudflare/sandbox@next 搭配 sandbox-next。在可行時，請規劃使用 sandbox-migrate-to-next 進行遷移，以便在 1.0 成為穩定版本時做好準備。除非使用者要求，否則請勿強制進行此移植。
1. 閘道 — 確認套件線路
在編寫程式碼之前，請檢查應用程式：
| 檢查項目 | 必須符合 |
|---|---|
| npm 依賴 | 預設 @cloudflare/sandbox（非 @next / 預覽標籤） |
| 容器映像 | 對應的穩定映像（非 cloudflare/sandbox:next） |
| 如果您發現… | 採取行動 |
|---|---|
@cloudflare/sandbox@next 或 next 映像 | 停止。 載入 sandbox-next。 |
使用者想要移植到 1.0 / @next | 停止。 載入 sandbox-migrate-to-next。請勿在穩定套件上部分套用預覽 API。 |
| 僅清理已棄用的穩定 API | 留在原地；請使用 2026 年棄用指南。這並非遷移至 @next。 |
切勿將穩定的 Worker 套件與 @next 容器映像（或反之）混合使用。
技能安裝：Agent 設定 · cloudflare/skills
2. 合約 — 不可協商的事項
await sandbox.exec(command)接受一個命令字串，並在命令完成時解析，回傳已緩衝的stdout/stderr/exitCode（以及相關欄位）。- 長時間運行和串流處理工作使用穩定的命令 API（
startProcess、execStream以及相關輔助函式），而非@next的單一控制代碼模型。請開啟命令文件；請勿在穩定版本上自行發明@next的output()控制代碼。 - 工作階段 (Sessions) 可以跨命令保留工作目錄和環境（預設工作階段 /
enableDefaultSession、createSession）。當狀態需要在呼叫之間傳遞時，請參閱工作階段文件。 - 互動式瀏覽器終端機通常使用穩定的
sandbox.terminal(request)以及工作階段/xterm 輔助函式，除非套件是@next，否則請勿使用預覽的createTerminal。 - 使用隧道或大型/二進位串流時，優先使用 RPC 傳輸。HTTP/WebSocket 傳輸已棄用（請參閱下方的清理指南）。
- 檔案、掛載點、連接埠、隧道、備份、生命週期和直譯器：請使用主要文件查閱簽章；信任已安裝的穩定型別。
- 非機密設定放在 Sandbox 環境中；即時憑證放在 Worker 中。當程序呼叫外部 API 時，請使用輸出處理常式 (outbound handlers)。
- 生產環境的預覽主機名稱在使用那些 URL 模式時，需要自訂網域的萬用 DNS。
- 在依賴仍然穩定時，請不要套用
@next的 argv/process.output()API。 - 自行部署的 bridge 請保持在穩定套件和映像上。Bridge
最小範例：
import { getSandbox, proxyToSandbox, Sandbox } from "@cloudflare/sandbox";
export { Sandbox };
const sandbox = getSandbox(env.Sandbox, "user-123");
const result = await sandbox.exec('python3 -c "print(2 + 2)"');
// result.stdout, result.exitCode, result.success
3. 檢索 — 為任務開啟文件
在實作之前請先擷取頁面。已安裝的穩定型別優先於猜測。
| 您需要… | 開啟 |
|---|---|
| 入門導覽 | Sandbox 概覽 |
| 第一個 Worker、範本、Docker | 開始使用 |
exec、串流、背景程序 | 命令 API · 執行命令 · 背景程序 · 串流輸出 |
| 工作階段 / 跨命令的 Shell 狀態 | 工作階段概念 · 工作階段 API |
getSandbox 選項、睡眠、銷毀 | 生命週期 API · Sandbox 選項 |
| 環境變數 | 環境變數 |
| 檔案 | 檔案 API · 管理檔案 · 檔案監控 |
| 儲存桶 / 掛載點 | 儲存 API · 掛載儲存桶 |
| 備份 | 備份 API · 備份與還原 |
| 連接埠、預覽 URL、暴露服務 | 連接埠 API · 暴露服務 |
| 隧道 | 隧道 API |
| Proxy / Workers 連線 | Proxy 請求 · Workers 連線 |
| 瀏覽器 / PTY 終端機 | 終端機 API · 終端機概念 · 瀏覽器終端機 |
| 程式碼直譯器 | 直譯器 API · 程式碼執行 |
| Sandbox 中的 Git | Git 工作流程 |
| 機密 / 對外流量 | 對外流量 |
| WebSocket | WebSocket 連線 |
| Docker-in-Docker | Docker in Docker |
| 生產部署 | 生產部署 |
| 容器概念 | 容器 |
| 操作指南索引 | 指南 |
| API 索引 | API 參考 |
| 保持在穩定版的已棄用 API | 2026 年棄用指南 |
| 自行部署的 bridge | Bridge · Bridge HTTP API |
範例（穩定版/main） | GitHub 上的範例 |
| 在 1.0 預覽上進行新工作 | sandbox-next · 1.0 預覽 |
將現有應用程式移植到 @next | sandbox-migrate-to-next · 遷移 |
清理已棄用的 API（保持在穩定版）
先更新套件和對應的映像，然後再依照指南進行。典型的搜尋：
rg 'SANDBOX_TRANSPORT|transport:|exposePort\(|enableDefaultSession|execStream\(|readFileStream|writeFileStream'
此路徑不會將您切換到 @next。
4. 發布前檢查
- Worker 套件和容器映像位於相同的穩定線路
- 根據已安裝的穩定型別進行型別檢查
- Sandbox 環境中無即時機密
- 如果使用已棄用的傳輸/輔助函式，請完成或追蹤 2026 年棄用 清理工作
- 當團隊準備好升級到 1.0 時，請使用
sandbox-migrate-to-next— 請勿在未經提示的情況下強制轉換