← Sandbox SDK / sandbox / guides

Průvodce migrací kvůli ukončení podpory 2026

Tato příručka provede migrací od funkcí Sandbox SDK, které byly označeny za zastaralé ve oznámení o ukončení podpory. Na těchto API nestavte novou práci. Dokončete tento úklid na stabilním balíčku a poté přejděte na 1.0 preview jakmile budete moci.

Oznámení a zdůvodnění najdete v záznam v changelogu o ukončení podpory.

Před změnou konfigurace transportu nebo relace aktualizujte na nejnovější verzi Sandbox SDK. Pokud váš projekt používá verzi starší než 0.9.1, nasaďte novější @cloudflare/sandbox balíček a image kontejneru před přechodem na RPC transport. Izolace relací pomocí enableDefaultSession: false vyžaduje Sandbox SDK 0.10.3 nebo novější, na 0.9.1-0.10.2, nejprve proveďte upgrade a až poté nastavte příznak.

Vyhledejte ve svém kódu zastaralou konfiguraci a API:

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

Zkontrolujte také veškerý kód, který používá pomocné funkce specifické pro streamy souborů nebo který spoléhá na to, že stav shellu přetrvává napříč jednotlivými exec() volání.

Transporty HTTP a WebSocket jsou zastaralé. Přejděte na transport RPC.

Chcete-li nakonfigurovat RPC transport pro všechny sandboxy ve vašem Workeru, nastavte SANDBOX_TRANSPORT v konfiguraci vašeho Workeru:

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

[vars]
SANDBOX_TRANSPORT = "rpc"

Chcete-li nakonfigurovat RPC transport pro konkrétní sandbox, předejte transport: "rpc" na 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",
});

Další informace najdete v tématu Režimy transportu.

Funkce desktopu byla odstraněna ve verzi 0.10.2. Tato funkce spouštěla plnohodnotnou linuxovou plochu uvnitř sandboxu pro automatizaci ve stylu computer-use. Pokud tuto podobu stále potřebujete, sestavte si ji znovu pomocí rozšíření než vestavěné desktopové API. Sandbox SDK používejte pro izolované spouštění příkazů, práci se soubory a běhové postupy, které desktop v sandboxu nevyžadují.

Nahraďte exposePort() s tunnels API pro veřejné URL. Tunnels API vyžaduje RPC transport.

Quick tunnely použijte pro vývoj, ukázky a krátkodobé adresy URL. Named tunnely použijte pro produkční provoz, příjem webhooků, zpětná volání OAuth a stabilní názvy hostitelů v zóně, kterou spravujete.

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 });

Pokud váš exposePort() použitý postup proxyToSandbox() k vkládání ověřování nebo přepisování odpovědí, zohledněte to ještě před přesunutím veřejné URL adresy na tunel.

Další informace najdete v tématu Tunnels a Zpřístupnění služeb.

Nastavte enableDefaultSession: false na getSandbox(). Operace bez explicitní session pak poběží izolovaně a nezdědí stav shellu z předchozích volání.

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",
});

Pokud váš kód očekává příkazy jako cd /workspace/app aby ovlivnil pozdější exec() volání vytvořte explicitní relaci a související příkazy spouštějte přes tuto relaci:

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");

Pro jednorázové příkazy předejte cwd nebo env přímo do exec() místo spoléhání na uchovaný stav shellu:

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

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

Další informace najdete v tématu Možnosti sandboxu a Relace.

Sandbox SDK sjednocuje samostatná streamovací API do základního exec(), readFile(), a writeFile() metody. Zkontrolujte kód, který závisí na pomocných funkcích specifických pro streamy, a přejděte na základní API tam, kde podporují streamované chování.

Pro výstup příkazu použijte exec() se streamovanými callbacky:

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}`);
	},
});

Pro velké nebo binární soubory použijte základní souborová API s RPC transportem. Předejte ReadableStream na writeFile(), nebo přečtěte soubor jako stream pomocí 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 },
});

Další informace najdete v tématu Příkazy a Soubory.

Tento kontrolní seznam použijte předtím, než se spolehnete na verzi Sandbox SDK, ze které byla odstraněna zastaralá API:

• RPC transport se konfiguruje pomocí SANDBOX_TRANSPORT=rpc nebo transport: "rpc".
• Ne websocket nebo http zůstává konfigurace přenosu.
• Ne exposePort() použití zůstává v migrované cestě.
• enableDefaultSession je nastaveno na false.
• Stavové pracovní postupy příkazů využívají sandbox.createSession().
• Jednorázové příkazy předávají cwd a env přímo.
• Kód pro streamování souborů a příkazů využívá základní API.
• Váš Worker byl nasazen a prošel kouřovým testem.

Kódovací agenti s Cloudflare Skills ↗ nainstalovaný (Nastavení agenta) by měly používat sandbox-stable pro práci na aktuálním stabilním balíčku a postupujte podle tento průvodce pro úklid zastaralého API při zachování stabilní verze. Pro úplný přechod na Sandbox SDK 1.0 (@next), použijte sandbox-migrate-to-next (a Průvodce migrací na 1.0) místo toho.

Až v tomto průvodci dokončíte změny stable-line, přejděte na Sandbox SDK 1.0 náhled na @cloudflare/sandbox@next jakmile budete moci. Tento preview je cestou k dalšímu stabilnímu hlavnímu vydání.

Viz Sandbox SDK 1.0 preview a Migrace na 1.0 preview.