本页将 @cloudflare/sandbox 0.12 的每个公开 API 映射到其替换项：1.0 类、平台 API、另一个 Cloudflare 产品，或你编写的代码。某些 API 不再需要。有关迁移步骤，请参阅 从 Sandbox SDK 0.x 迁移。
在表格中，container 是 Durable Object 中的 this.ctx.container，files 是 Files 实例。类型 列使用这些值：
| 类型 | 含义 |
|---|---|
| 原生 | 直接调用 container 或其他平台 API。 |
| 包 | 使用 @cloudflare/sandbox 1.0 中的类，例如 Files。 |
| 模式 | 自己编写。当某页展示做法时，备注会链接到它。 |
| 产品 | 使用另一个 Cloudflare 产品。 |
| 已移除 | 不再需要。备注说明改为做什么。 |
有关步骤，请参阅 替换 Sandbox 类。这些 API 创建 sandbox 并控制其容器运行多久：
| 0.12 | 类型 | 替换项 | 备注 |
|---|---|---|---|
class X extends Sandbox, export { Sandbox } |
已移除 | class X extends DurableObject |
从 container 构造该包中的类。 |
getSandbox(ns, id, options) |
原生 | env.NS.getByName(id) |
自己验证名称。 |
normalizeId, setSandboxName() |
已移除 | 自己将名称转为小写 | 仅在名称会成为主机名时需要。 |
sleepAfter, setSleepAfter() |
原生 | container.setInactivityTimeout(ms) |
最多 6 小时。在 start() 之后调用，并在构造函数中再次调用。 |
keepAlive, setKeepAlive() |
模式 | 在工作仍在进行时向容器发送请求的 alarm | 请参阅 Sandbox 生命周期。 |
renewActivityTimeout() |
原生 | 对 Durable Object 的任何请求 | 超时从 Durable Object 变为不活动时开始计算。 |
containerTimeouts, setContainerTimeouts() |
已移除 | AbortSignal |
|
transport, setTransport(), SANDBOX_TRANSPORT |
已移除 | 不需要 | container.exec() 和 Files 直接到达容器。移除该设置。 |
labels, setLabels() |
原生 | container.start({ image, enableInternet, labels }) |
|
configure() |
已移除 | 每次调用上的选项 | |
setEnvVars()、类 envVars |
原生 | container.start({ env }) 或 container.exec(argv, { env }) |
exec() 不继承 start() 变量，PATH 除外。 |
类 entrypoint、enableInternet |
原生 | container.start({ entrypoint, enableInternet }) |
enableInternet 默认为 false。在 0.12 中默认为 true。 |
类 defaultPort、requiredPorts |
原生 | container.getTcpPort(port) |
|
start() |
原生 | container.start({ image, enableInternet }) |
不会等待容器。 |
startAndWaitForPorts(), waitForPort() |
模式 | 重试 getTcpPort(port).fetch() |
预览 Web 应用 展示了就绪检查。 |
stop(), destroy() |
原生 | container.signal(), container.destroy() |
|
getState() |
原生 | container.running, container.monitor() |
|
getContainerPlacementId() |
模式 | 用 container.exec() 从 /proc/1/environ 读取 CLOUDFLARE_PLACEMENT_ID |
容器的主进程有该变量。命令没有。 |
onStart, onStop, onError, onActivityExpired |
模式 | 围绕 start() 和 monitor() 的代码 |
|
schedule(), listSchedules(), getSchedule(), deleteSchedules(), alarm() |
原生 | Durable Object alarms | 每个对象一个 alarm。如果需要多个，请存储自己的调度。 |
fetch(), containerFetch() |
原生 | container.getTcpPort(port).fetch() |
有关步骤，请参阅 更改命令调用。这些 API 运行命令：
| 0.12 | 类型 | 替换项 | 备注 |
|---|---|---|---|
exec(command, options) |
原生 | container.exec(argv, options) |
output() 返回字节和 exitCode。success 是 exitCode === 0。 |
stream, onOutput, onComplete, onError |
原生 | 读取 stdout 和 stderr，并 await exitCode |
|
execStream() |
原生 | 来自 container.exec(argv) 的 stdout 流 |
在响应上设置 Content-Type: text/event-stream。请参阅 流式输出。 |
timeout, signal |
原生 | 在 timeout 下运行命令，或传入你清除的计时器上的 signal |
退出代码 124 或 137 表示时间已到。请参阅替换超时设置。 |
cwd, env |
原生 | 相同选项 | 传入 cwd: "/workspace" 和 env，这是 0.12 默认设置的。 |
encoding |
已移除 | 自己解码字节 | |
isExecResult(), isProcess(), isProcessStatus() |
已移除 | 不需要 | exec() 返回 ExecProcess。TypeScript 类型替代了这些守卫。 |
有关步骤，请参阅 迁移后台进程。每个替换项都基于 运行后台进程 中的进程目录。这些 API 运行并管理后台进程：
| 0.12 | 类型 | 替换项 | 备注 |
|---|---|---|---|
startProcess() |
模式 | startProcess(id, argv)，将进程 ID、输出和退出码写入文件 |
传入 cwd: "/workspace" 和 env，这是 0.12 设置的。请参阅 添加进程方法。 |
Process.getStatus(), getProcess(), listProcesses() |
模式 | status()，以及遍历进程目录的 listProcesses() 方法 |
|
getProcessLogs(), Process.getLogs() |
模式 | 每个流的 logs() |
|
streamProcessLogs() |
模式 | follow()，它流式传输 tail -F --pid |
名为 stdout、stderr 和 exit 的事件，而不是 LogEvent 对象。 |
Process.waitForLog() |
模式 | waitForLog()，用 grep -E 轮询日志文件 |
转义 0.12 字符串模式。请参阅 等待输出或退出。 |
Process.waitForExit() |
模式 | 调用 status() 直到进程结束的 waitForExit() 方法 |
|
Process.waitForPort() |
模式 | 重试 getTcpPort(port).fetch() |
预览 Web 应用 展示了就绪检查。 |
Process.kill(), killProcess() |
模式 | stop()，向进程组发送 SIGTERM |
0.12 会在 5 秒后发送 SIGKILL。 |
killAllProcesses() |
模式 | 对 listProcesses() 返回的每个进程调用 stop() |
|
cleanupCompletedProcesses(), autoCleanup |
已移除 | 不需要 | 两者在 0.12 中都不做任何事。用 rm -rf 删除已结束的进程目录。 |
onStart, onOutput, onError |
模式 | startProcess()、follow() 之后的代码，以及抛出或返回 false 的启动 |
|
onExit |
模式 | 每分钟检查每个进程的 alarm | 请参阅 替换回调。 |
有关步骤，请参阅 替换会话。这些 API 在命令之间保留状态：
| 0.12 | 类型 | 替换项 | 备注 |
|---|---|---|---|
createSession(), getSession(), deleteSession() |
已移除 | 每次调用上的 cwd 和 env |
|
enableDefaultSession |
已移除 | 每次调用上的 cwd 和 env |
cd 和 export 不会带到下一次。 |
isolation |
已移除 | 单独的 sandbox | |
commandTimeoutMs |
已移除 | 每条命令中的 timeout |
ExecutionSession 方法的映射方式与顶层方法相同。
有关步骤，请参阅 更改文件调用。这些 API 读写文件：
| 0.12 | 类型 | 替换项 | 备注 |
|---|---|---|---|
readFile(), readFileStream() |
包 | files.readFile() |
返回一个 Response。使用 .text()、.arrayBuffer() 或响应正文；正文包含文件字节，而不是服务器发送事件。 |
writeFile() |
包 | files.writeFile() |
先用 mkdir() 创建缺失的父目录。传入字节而不是 base64。 |
mkdir() |
包 | files.mkdir() |
|
deleteFile() |
包 | files.remove() |
带有 recursive: true 时也会删除目录。 |
renameFile(), moveFile() |
包 | files.rename() |
跨文件系统操作会失败并返回 EXDEV。与 mv 不同，它不会将源移动到现有目录中。 |
listFiles() |
包 | files.readDirectory() |
一层。包含隐藏条目。 |
listFiles({ recursive: true }) |
模式 | 遍历 readDirectory() |
请参阅 列出文件。 |
exists() |
包 | files.stat() |
捕获带有 ENOENT 的 SandboxFileError。 |
| 文件元数据 | 包 | files.stat(), files.lstat() |
|
watch(), checkChanges() |
模式 | 通过 container.exec() 运行 inotifywait -m |
请参阅 替换文件监视。 |
collectFile(), streamFile() |
已移除 | Response 正文 |
|
parseSSEStream(), responseToAsyncIterable(), asyncIterableToSSEStream() |
已移除 | ExecProcess 上的 ReadableStream 对象 |
要将输出作为 server-sent events 发送到浏览器，请参阅 流式命令输出。 |
WriteFileResult、ReadFileResult 和其他结果类型 |
已移除 | void、Response 或 SandboxFileStat |
失败会抛出 SandboxFileError。 |
有关步骤，请参阅 迁移预览 URL 和 迁移隧道。这些 API 使容器中的服务器可从外部访问：
| 0.12 | 类型 | 替换项 | 备注 |
|---|---|---|---|
exposePort(), unexposePort(), getExposedPorts(), isPortExposed() |
模式 | 基于 0.12 portTokens 键的方法 |
0.12 签发的 URL 继续有效。请参阅 替换预览调用。 |
validatePortToken() |
模式 | 对已存储令牌的恒定时间检查 | |
proxyToSandbox(), SandboxEnv |
模式 | 将 <port>-<name>-<token> 主机名路由到 getByName() |
|
wsConnect(request, port) |
原生 | container.getTcpPort(port).fetch(request) |
桥接 WebSocket 以保持容器运行。 |
tunnels.get(port), tunnels.list(), tunnels.destroy(port) |
模式 | 运行 cloudflared 的 openTunnel()、listTunnels() 和 closeTunnel() |
需要 enableInternet: true。请参阅 从 Durable Object 运行 cloudflared。 |
tunnels.get(port, { name }) |
模式 | 基于 0.12 tunnels 键的 resumeTunnel() 和 deleteTunnel() |
0.12 创建的主机名继续有效。请参阅 保留 0.12 创建的命名隧道。 |
CLOUDFLARE_API_TOKEN |
模式 | 相同的密钥 | 在你运行或删除 0.12 创建的命名隧道期间保留它。 |
CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_TUNNEL_ACCOUNT_ID, CLOUDFLARE_ZONE_ID |
已移除 | 不需要 | 代码读取 0.12 存储的账户和 zone。 |
有关步骤，请参阅 迁移浏览器终端。这些 API 将浏览器终端连接到 shell：
| 0.12 | 类型 | 替换项 | 备注 |
|---|---|---|---|
terminal(), session.terminal() |
模式 | getByName(name).fetch(request)，以及用 exec(argv, { pty }) 附加 tmux 客户端的 handler |
在 /workspace 中用 env 启动 shell，这是 0.12 设置的。请参阅 将终端附加到 tmux。 |
proxyTerminal() |
模式 | 相同的 fetch() 调用，会话在查询字符串中 |
请参阅 转发 WebSocket。 |
终端打开的会话的 cwd 和 env |
模式 | tmux new-session 的 -c 和 -e 选项 |
tmux 在创建会话时应用它们。 |
shell 选项 |
模式 | tmux 命令中会话名称之后的命令 | |
@cloudflare/sandbox/xterm, SandboxAddon, SandboxAddonOptions, ConnectionState, ConnectionTarget |
模式 | 带有页面会重新打开的 WebSocket 的 xterm.js | 发送 {"type":"ready"}，以便切换前加载的页面继续有效。请参阅 替换 SandboxAddon。 |
| 终端重连与回放 | 模式 | tmux 保留会话并重绘屏幕 | 更早的输出留在 tmux 历史中。请参阅 终端上的变化。 |
有关步骤，请参阅 迁移出站规则。这些 API 控制容器中的代码发出的请求：
| 0.12 | 类型 | 替换项 | 备注 |
|---|---|---|---|
allowedHosts, deniedHosts, outbound, outboundByHost, outboundHandlers, outboundProxies, outboundProxy |
模式 | 按 0.12 顺序应用规则的 WorkerEntrypoint |
handler 接受 (request, env, params)。请参阅 在 entrypoint 中应用规则。 |
读取 Workers 绑定的 outboundByHost handler |
模式 | 每个主机名一个 WorkerEntrypoint |
请参阅 从容器访问 Workers 绑定。 |
interceptHttps |
原生 | 对每个 sandbox 调用 container.interceptOutboundHttps("*", fetcher) |
将证书添加到系统捆绑包，并设置 NODE_EXTRA_CA_CERTS 和 REQUESTS_CA_BUNDLE。0.12 仅在 interceptHttps = true 时检查 HTTPS。请参阅 请求方面的变化。 |
setAllowedHosts(), setDeniedHosts(), allowHost(), denyHost(), removeAllowedHost(), removeDeniedHost(), setOutboundHandler(), setOutboundByHost(), setOutboundByHosts(), removeOutboundByHost() |
模式 | 更新 OUTBOUND_CONFIGURATION 键并再次注册 entrypoint 的方法 |
0.12 存储的规则继续生效。请参阅 替换运行时 setter。 |
ContainerProxy |
已移除 | 导出你自己的 entrypoint | 从 Worker 的导出中移除它。 |
gitCheckout() |
模式 | 在 /workspace 中 exec() git clone --filter=blob:none |
请参阅 替换 gitCheckout()。对于私有仓库，请参阅 克隆私有仓库。 |
有关步骤，请参阅 迁移存储桶挂载。这些 API 在容器中挂载对象存储：
| 0.12 | 类型 | 替换项 | 备注 |
|---|---|---|---|
带 S3 端点的 mountBucket() |
包 | S3Mount.mount()，并从 Worker 导出 S3Gateway |
凭据留在 Worker 中。请参阅 挂载存储桶。 |
带 R2 绑定的 mountBucket() |
包 | 使用 R2 S3 端点的 S3Mount.mount() |
需要该存储桶的 R2 API 令牌。1.0 无法通过绑定挂载。 |
prefix, readOnly, s3fsOptions |
包 | keyPrefix, access, s3fsOptions |
keyPrefix 没有前导 /，access 是必填的，s3fsOptions 是对象。 |
credentials、R2_* 和 AWS_* 变量 |
包 | source.credentials |
不从环境读取。 |
credentialProxy, provider |
已移除 | 不需要 | S3Gateway 为每个请求签名。S3Mount 始终设置 nomixupload，而 0.12 仅对 R2 添加它。 |
localBucket |
包 | 在 wrangler dev 下配合本地兼容 S3 的服务器使用 S3Mount |
需要 Wrangler 4.137.0 或更高版本。请参阅 替换 localBucket。 |
unmountBucket() |
包 | S3Mount.unmount() |
当有进程使用该路径时抛出 S3_MOUNT_BUSY。 |
BucketMountError, BucketUnmountError, InvalidMountConfigError, MissingCredentialsError, S3FSMountError |
包 | SandboxS3MountError |
无效请求会抛出 TypeError。 |
| 与出站规则一起的挂载 | 模式 | 在 interceptAllOutboundHttp() 之前挂载 |
在 catch-all intercept 之后注册的挂载会失败。请参阅 如果你已迁移出站规则。 |
有关步骤，请参阅 迁移备份。这些 API 保存并恢复目录：
| 0.12 | 类型 | 替换项 | 备注 |
|---|---|---|---|
createBackup(), restoreBackup() |
包 | DirectoryBackup 的 backup() 和 restore() |
你的 Durable Object 存储记录。对于整个文件系统，使用 container.snapshotContainer()。 |
name, gitignore |
包 | 同名的 DirectoryBackup 选项 |
gitignore 不需要镜像中有 git。 |
excludes |
包 | exclude |
.gitignore 语法。以 **/ 开头的模式可匹配任意深度，与 0.12 的模式行为相同。 |
ttl |
模式 | 存储在存储桶中、备份旁边的过期时间 | 0.12 拒绝过期恢复并保留对象。 |
multipart, localBucket, compression |
已移除 | 不需要 | 每个备份都分片通过 R2 绑定。 |
BACKUP_BUCKET |
原生 | R2 绑定 | 将其名称作为 DirectoryBackup 的 binding 传入。 |
BACKUP_BUCKET_NAME、BACKUP_BUCKET_ENDPOINT、R2 访问密钥 |
已移除 | R2 绑定 | 容器永远不会持有存储桶凭据。 |
BackupNotFoundError |
包 | 代码为 BACKUP_NOT_FOUND 的 SandboxBackupError |
|
BackupExpiredError |
模式 | 你的过期检查抛出的错误 | |
InvalidBackupConfigError |
已移除 | TypeError |
|
BackupCreateError, BackupRestoreError |
包 | SandboxFileError 或 SandboxBackupError |
请参阅 DirectoryBackup 错误。 |
| 0.12 制作的备份 | 模式 | 对 backups/<id>/data.sqsh 运行 unsquashfs，然后 backup() |
请参阅 转换 0.12 创建的备份。 |
这些 API 来自代码解释器和该包的子路径导出：
| 0.12 | 类型 | 替换项 | 备注 |
|---|---|---|---|
runCode(), createCodeContext(), listCodeContexts(), deleteCodeContext(), CodeInterpreter |
模式 | 每个上下文一个 IPython kernel，或用于 JavaScript 的 Dynamic Worker | 请参阅 替换代码解释器。 |
runCodeStream(), onStdout, onStderr, onResult |
模式 | 带有 python3 - 及其 stdout 的命令 |
请参阅 替换流式输出。 |
@cloudflare/sandbox/opencode, createOpencode(), createOpencodeServer(), OpencodeOptions, OpencodeResult, OpencodeServer, OpencodeStartupError |
模式 | opencode serve 和 OpenCode SDK 客户端 |
请参阅 启动 OpenCode 服务器。 |
proxyToOpencode(), proxyToOpencodeServer() |
模式 | Durable Object 中的 fetch()，它转发到服务器端口 |
请参阅 启动 OpenCode 服务器。 |
@cloudflare/sandbox/openai, Shell, Editor, CommandResult, FileOperationResult |
模式 | 你自己的 Shell 和 Editor |
@openai/agents 中的 ShellResult 和 ApplyPatchResult 替换结果类型。请参阅 为 OpenAI agent 提供 shell 和编辑器。 |
@cloudflare/sandbox/bridge, bridge(), resolveWorkspacePath(), shellQuote(), BridgeConfig, BridgeEnv, WorkerHandlers |
模式 | 你自己的 Worker 路由 | 请参阅 替换 bridge。 |
WarmPool, WarmPoolConfig, PoolStats |
已移除 | 在请求需要时启动每个 sandbox | 请参阅 移除 WarmPool。 |
0.12 发布了供 Sandbox 类构建的容器镜像：
| 0.12 | 类型 | 替换项 | 备注 |
|---|---|---|---|
cloudflare/sandbox、-python、-opencode 和 -musl 镜像 |
已移除 | 你自己的 linux/amd64 镜像 |
如果使用 Files、S3Mount 或 DirectoryBackup，请将 sandbox-shim 复制到镜像中。请参阅要求。 |
带有 USER root 的 docker:dind-rootless |
模式 | 带有 --ip-forward=false 的 docker:dind |
请参阅 在 sandbox 内运行 Docker。 |
这些 API 报告失败并与容器通信：
| 0.12 | 类型 | 替换项 | 备注 |
|---|---|---|---|
ContainerUnavailableError, OperationInterruptedError, RPCTransportError, SessionTerminatedError |
已移除 | 来自 container 的原生错误 |
不包装。 |
ProcessExitedBeforeReadyError, ProcessReadyTimeoutError |
模式 | 你的就绪检查结果 | 请参阅 预览 Web 应用。 |
isPlatformTransientError(), isDurableObjectCodeUpdateReset() |
已移除 | error.retryable 和 error.overloaded |
当 retryable 为 true 时，用新 stub 重试幂等调用；当 overloaded 为 true 时永不重试。该包不重试。请参阅 错误处理。 |
SandboxClient, BackupClient, CommandClient, FileClient, GitClient, InterpreterClient, PortClient, ProcessClient, UtilityClient |
已移除 | container 和 Files |
从你的 Durable Object 调用它们。 |
SANDBOX_LOG_LEVEL, SANDBOX_LOG_FORMAT |
已移除 | 你自己的日志 | 该包不记录日志。从 Worker 记录，并在 Workers Logs 中读取。 |
这些 0.12 类型描述前面各节中方法的选项和结果。每种类型随其方法一起迁移：
| 0.12 | 类型 | 替换项 | 备注 |
|---|---|---|---|
SandboxOptions, SandboxTransport, ISandbox, ContainerStub |
已移除 | 你的类 | 请参阅 类、标识与生命周期。 |
BaseExecOptions, ExecOptions, StreamOptions, ExecResult, ExecEvent, ExecuteRequest, CommandExecuteResponse, CommandsResponse |
原生 | ContainerExecOptions, ExecProcess, ExecOutput |
wrangler types 会生成它们。 |
PtyOptions |
原生 | ContainerExecPtyOptions |
作为 pty 传给 container.exec()。shell 放在命令中。 |
SessionOptions, SessionRequest, CreateSessionRequest, CreateSessionResponse, DeleteSessionRequest, DeleteSessionResponse |
已移除 | 每次调用上的 cwd 和 env |
|
ProcessOptions, ProcessStatus, ProcessStartResult, ProcessListResult, ProcessInfoResult, ProcessKillResult, ProcessLogsResult, ProcessCleanupResult, StartProcessRequest, WaitForLogResult, WaitForPortOptions |
模式 | 你的进程方法的类型 | 请参阅 迁移后台进程。 |
ReadFileRequest, WriteFileRequest, FileOperationRequest, MkdirRequest, ListFilesOptions |
包 | FileOperationOptions, MkdirOptions, RemoveOptions, FileContent |
|
FileMetadata, FileChunk, FileStreamEvent |
已移除 | files.readFile() 返回的 Response |
|
WatchOptions, FileWatchSSEEvent, CheckChangesOptions, CheckChangesResult |
模式 | 你的 inotifywait 读取器返回的事件 |
请参阅 替换文件监视。 |
TunnelOptions, TunnelInfo, QuickTunnelInfo, NamedTunnelInfo |
模式 | 你的隧道方法的类型 | 请参阅 迁移隧道。 |
GitCheckoutRequest, GitCheckoutResult |
模式 | 你的 git clone 命令的参数和输出 |
请参阅 替换 gitCheckout()。 |
MountBucketOptions, RemoteMountBucketOptions, LocalMountBucketOptions, BucketCredentials, BucketProvider |
包 | S3MountRequest |
|
BackupOptions, DirectoryBackup, RestoreBackupResult |
包 | DirectoryBackupOptions, DirectoryBackupRecord, DirectoryRestoreOptions |
DirectoryBackupRecord 增加 size、name、sha256 和 format，并去掉 localBucket。restore() 不返回任何内容。在 1.0 中，DirectoryBackup 是保存和恢复备份的类。 |
CodeContext, CreateContextOptions, RunCodeOptions, ExecutionCallbacks, ExecutionResult |
模式 | 你的 kernel 的 CodeContext 和 Execution 类型 |
请参阅 替换代码解释器。 |
ContainerUnavailableContext, ContainerUnavailableReason, OperationInterruptedContext, OperationInterruptedReason, RPCTransportContext, RPCTransportErrorKind |
已移除 | 不需要 | 它们的错误已移除。 |
SandboxClientOptions, RequestConfig, ResponseHandler, BaseApiResponse, ErrorResponse, PingResponse |
已移除 | 不需要 | 客户端已移除。 |