用途:该技能面向使用稳定版 @cloudflare/sandbox 包在 Cloudflare Containers 上构建或调试隔离 Linux 环境的场景,由 Workers 驱动。它定位为入口检查、契约约束与文档检索地图,而非完整手册。
主要能力与用法:写代码前先核对应用,npm 依赖应为默认 @cloudflare/sandbox(非 @next 或 preview 标签),容器镜像需匹配稳定版(非 cloudflare/sandbox:next)。若发现 @next 包或 next 镜像,应停止并改用 sandbox-next;若用户要迁移到 1.0/@next,应改用 sandbox-migrate-to-next,不要在稳定包上混用预览 API。仅清理已弃用的稳定 API 时仍留在本技能,参考 2026 弃用指南。切勿混用稳定 Worker 包与 @next 容器镜像。
契约要点:await sandbox.exec(command) 接收命令字符串,命令结束时解析,返回缓冲的 stdout/stderr/exitCode 等字段;长时与流式任务使用稳定命令 API(startProcess、execStream 等),不要臆造 @next 的 output() 句柄。会话可跨命令保留工作目录与环境(默认会话/enableDefaultSession、createSession)。交互式浏览器终端常用 sandbox.terminal(request) 与会话/xterm 辅助。使用隧道或大/二进制流时优先 RPC 传输,HTTP/WebSocket 传输已弃用。文件、挂载、端口、隧道、备份、生命周期与解释器以主文档签名为准,信任已安装的稳定类型。非机密配置放 sandbox env,实时凭据放 Worker;进程调用外部 API 时用出站处理器。生产预览主机名在自定义域上需通配 DNS。
检索:实现前先打开对应文档页,已安装稳定类型优先于猜测。文档涵盖入门、命令、会话、生命周期、环境变量、文件、存储与挂载、备份、端口、隧道、代理、终端、解释器、Git、出站流量、WebSocket、Docker-in-Docker、生产部署等。
限制:默认镜像不含 Python,需匹配 -python 镜像;自部署 bridge 须保持稳定包与镜像;发布前需确保 Worker 包与容器镜像同一稳定线、对已安装稳定类型做类型检查、sandbox env 无实时机密,并处理或跟踪 2026 弃用清理。团队准备好 1.0 时用 sandbox-migrate-to-next,不要未经要求强制切换。