用途:在 Cloudflare Containers 上通过 Workers 驱动隔离 Linux 环境,专门针对 @cloudflare/sandbox@next(1.0 预览)这一包线构建或调试应用。新项目推荐使用该线;仍用默认包的应用应改用 sandbox-stable,迁移需通过 sandbox-migrate-to-next。
主要能力与契约:sandbox.exec(argv) 接收 argv 列表,进程启动即 resolve,返回句柄而非最终结果;用 output()、logs()、waitForExit()、waitForPort()、waitForLog()、kill(signal?) 收集结果。无隐式 shell,需显式如 ["/bin/bash", "-lc", script]。每次启动相互独立,cd/export 不跨次生效,需按次传 cwd 与 env 或写成单个脚本。句柄无 stdin,交互用 createTerminal + connect。本地等待超时或 AbortSignal 只取消等待,不杀进程,需用 kill 或远程超时。getProcess/listProcesses/getTerminal/listTerminals 不会启动容器,无容器时返回 null/[]。进程与终端 ID 属于当前容器,需持久化完整作业信息。setEnvVars/启动 env 只放非机密配置,凭据留在 Worker,外部调用用 outbound handlers。不要使用已移除的稳定版 API。
使用方式:写代码前先检查 npm 依赖与容器镜像是否同为 @next 线,不可混用 @next Worker 包与稳定镜像。Python 需匹配 -python 镜像,默认镜像不含 Python。实现前先查对应文档页(预览总览、Get started、Process execution、Processes API、Lifecycle、Environment、Terminals、Interpreter、Extensions、Errors、Troubleshooting、API reference 等)。
限制:本技能是门禁、契约与检索地图,非完整手册;API 会变,应以预览文档和已安装的 @next 类型为准。发布前需锁定 lockfile 与 Dockerfile 同一 @next 线、对已安装类型做类型检查、确保沙箱 env 无实时机密;使用生产预览主机名时需自定义域名的通配 DNS。安装方式与更多细节资料未提供。