← Sandbox SDK / sandbox / guides

Руководство по миграции в связи с прекращением поддержки в 2026 году

В этом руководстве описан переход от функций Sandbox SDK, признанных устаревшими в объявление об устаревании. Не разрабатывайте новую функциональность на основе этих API. Завершите эту очистку в стабильном пакете, затем переходите к 1.0 preview когда это возможно.

Анонс и обоснование см. в запись об устаревании в журнале изменений.

Обновитесь до последней версии Sandbox SDK, прежде чем менять конфигурацию транспорта или сессии. Если ваш проект использует версию раньше, чем 0.9.1, разверните более новый @cloudflare/sandbox пакет и образ контейнера, прежде чем переключаться на транспорт RPC. Изоляция сессий с enableDefaultSession: false требует Sandbox SDK 0.10.3 или новее, на 0.9.1-0.10.2, сначала выполните обновление, затем установите флаг.

Найдите в своей кодовой базе устаревшие конфигурации и API:

rg 'SANDBOX_TRANSPORT|transport:|exposePort\(|enableDefaultSession|execStream\(|readFileStream|writeFileStream'

Также проверьте код, который использует вспомогательные функции для потоковой работы с файлами или зависит от сохранения состояния shell между отдельными exec() вызовы.

HTTP- и WebSocket-транспорты устарели. Переходите на RPC-транспорт.

Чтобы настроить транспорт RPC для всех песочниц в вашем Worker, задайте SANDBOX_TRANSPORT в конфигурации вашего Worker:

{
	"vars": {
		"SANDBOX_TRANSPORT": "rpc"
	}
}

[vars]
SANDBOX_TRANSPORT = "rpc"

Чтобы настроить транспорт RPC для конкретной песочницы, передайте transport: "rpc" к getSandbox():

import { getSandbox } from "@cloudflare/sandbox";

const sandbox = getSandbox(env.Sandbox, "user-123", {
	transport: "rpc",
});

import { getSandbox } from "@cloudflare/sandbox";

const sandbox = getSandbox(env.Sandbox, "user-123", {
	transport: "rpc",
});

Подробнее см. в Режимы транспорта.

Функция рабочего стола была удалена в 0.10.2. Эта функция запускала полноценный рабочий стол Linux внутри песочницы для автоматизации в стиле computer-use. Если вам всё ещё нужна такая конфигурация, воссоздайте её с помощью расширения а не встроенный API рабочего стола. Используйте Sandbox SDK для изолированного выполнения команд, операций с файлами и сценариев выполнения, которые не требуют рабочего стола внутри sandbox.

Замените exposePort() с tunnels API для публичных URL. tunnels API требует RPC-транспорта.

Используйте быстрые туннели для разработки, демонстраций и URL с коротким сроком жизни. Используйте именованные туннели для продакшен-трафика, обработки webhook, OAuth callback и стабильных имён хостов в зоне, которую вы контролируете.

import { getSandbox } from "@cloudflare/sandbox";

const sandbox = getSandbox(env.Sandbox, "my-sandbox", {
	transport: "rpc",
});

const server = await sandbox.startProcess("python -m http.server 8080");
await server.waitForPort(8080);

const tunnel = await sandbox.tunnels.get(8080);
return Response.json({ url: tunnel.url });

import { getSandbox } from "@cloudflare/sandbox";

const sandbox = getSandbox(env.Sandbox, "my-sandbox", {
	transport: "rpc",
});

const server = await sandbox.startProcess("python -m http.server 8080");
await server.waitForPort(8080);

const tunnel = await sandbox.tunnels.get(8080);
return Response.json({ url: tunnel.url });

Если ваш exposePort() сценарий использовал proxyToSandbox() для внедрения аутентификации или перезаписи ответов, учтите это поведение перед переносом публичного URL на туннель.

Подробнее см. в Tunnels и Публикация сервисов.

Задайте enableDefaultSession: false на getSandbox(). В таком случае операции без явной сессии выполняются изолированно и не наследуют состояние оболочки от предыдущих вызовов.

import { getSandbox } from "@cloudflare/sandbox";

const sandbox = getSandbox(env.Sandbox, "user-123", {
	enableDefaultSession: false,
	transport: "rpc",
});

import { getSandbox } from "@cloudflare/sandbox";

const sandbox = getSandbox(env.Sandbox, "user-123", {
	enableDefaultSession: false,
	transport: "rpc",
});

Если ваш код ожидает команды вида cd /workspace/app чтобы повлиять на последующие exec() вызовов, создайте явную сессию и выполняйте связанные команды через неё:

const buildSession = await sandbox.createSession({
	id: "build",
	cwd: "/workspace/app",
});

await buildSession.exec("npm install");
await buildSession.exec("npm test");

const buildSession = await sandbox.createSession({
	id: "build",
	cwd: "/workspace/app",
});

await buildSession.exec("npm install");
await buildSession.exec("npm test");

Для разовых команд передайте cwd или env напрямую в exec() вместо того чтобы полагаться на сохраненное состояние оболочки:

await sandbox.exec("npm test", {
	cwd: "/workspace/app",
	env: {
		NODE_ENV: "test",
	},
});

await sandbox.exec("npm test", {
	cwd: "/workspace/app",
	env: {
		NODE_ENV: "test",
	},
});

Подробнее см. в Параметры песочницы и Сеансы.

Sandbox SDK объединяет отдельные API потоковой передачи в базовый exec(), readFile(), а также writeFile() методы. Проверьте код, зависящий от вспомогательных функций для потоков, и перейдите на базовые API там, где они поддерживают потоковое поведение.

Для вывода команд используйте exec() с потоковыми callback-функциями:

await sandbox.exec("npm install", {
	stream: true,
	onOutput: (stream, data) => {
		console.log(`[${stream}] ${data}`);
	},
});

await sandbox.exec("npm install", {
	stream: true,
	onOutput: (stream, data) => {
		console.log(`[${stream}] ${data}`);
	},
});

Для больших или бинарных файлов используйте базовые файловые API с RPC-транспортом. Передайте ReadableStream к writeFile(), либо прочитать файл как поток с помощью encoding: "none":

const request = await fetch("https://example.com/archive.tar.gz");

if (!request.body) {
	throw new Error("Expected archive response body");
}

await sandbox.writeFile("/workspace/archive.tar.gz", request.body);

const file = await sandbox.readFile("/workspace/archive.tar.gz", {
	encoding: "none",
});

return new Response(file.content, {
	headers: { "Content-Type": file.mimeType },
});

const request = await fetch("https://example.com/archive.tar.gz");

if (!request.body) {
	throw new Error("Expected archive response body");
}

await sandbox.writeFile("/workspace/archive.tar.gz", request.body);

const file = await sandbox.readFile("/workspace/archive.tar.gz", {
	encoding: "none",
});

return new Response(file.content, {
	headers: { "Content-Type": file.mimeType },
});

Подробнее см. в Команды и Файлы.

Прежде чем полагаться на релиз Sandbox SDK, из которого удалены устаревшие API, пройдите этот чек-лист:

• RPC-транспорт настраивается с помощью SANDBOX_TRANSPORT=rpc или transport: "rpc".
• Нет websocket или http конфигурация транспорта остаётся прежней.
• Нет exposePort() использование сохраняется в перенесённом пути.
• enableDefaultSession имеет значение false.
• Сценарии с отслеживанием состояния используют sandbox.createSession().
• Разовые команды передают cwd и env напрямую.
• Код потоковой передачи файлов и команд использует базовые API.
• Ваш Worker развёрнут и прошёл smoke-тестирование.

ИИ-агенты для программирования с Cloudflare Skills ↗ установлен (Настройка агента) должны использовать sandbox-stable для работы с текущим стабильным пакетом, а затем переходите на это руководство для очистки устаревшего API при сохранении стабильной версии. Для полного перехода на Sandbox SDK 1.0 (@next), используйте sandbox-migrate-to-next (а также Руководство по переходу на 1.0) вместо этого.

Завершив описанные в этом руководстве изменения для stable line, переходите к Sandbox SDK 1.0 preview на @cloudflare/sandbox@next когда это возможно. Этот предварительный выпуск является путём к следующему стабильному основному релизу.

См. превью Sandbox SDK 1.0 и Переход на предварительную версию 1.0.