← Cloudflare Workers / workers / static-assets / migration-guides

Migrace z Pages na Workers

Full-stack aplikace, včetně statických front-end assets a back-end API i stránek vykreslovaných na straně serveru (SSR), můžete nasadit pomocí Cloudflare Workers.

Stejně jako u Pages jsou požadavky na statické prostředky ve Workers zdarma a Pages Functions volání jsou účtována stejnou sazbou jako Workers, takže můžete očekávat podobnou nákladovou strukturu.

Na rozdíl od Pages má Workers k dispozici výrazně širší sadu funkcí (včetně Durable Objects, Cron Triggers a komplexnější Observability). Úplný seznam najdete na dolní části této stránky.

Migrace z Cloudflare Pages na Cloudflare Workers bývá většinou přímočará. Níže jsou uvedeny nejčastější kroky, které při migraci projektu obvykle budete potřebovat.

Pokud váš projekt Pages používá oblíbený framework, většina frameworků již má k dispozici adaptéry pro Cloudflare Workers. Nahraďte veškeré adaptéry určené pro Pages jejich ekvivalenty pro Workers a řiďte se pokyny, které poskytují.

Pokud jej váš projekt ještě nemá, vytvořte Konfigurační soubor Wrangler (buď wrangler.jsonc, wrangler.json nebo wrangler.toml) v kořenovém adresáři vašeho projektu. Dvě povinná pole jsou:

• name

  Nastavte sem název Workeru, na který chcete nasazovat. Může být stejný jako název vašeho stávajícího projektu Pages, pokud splňuje omezení pro názvy u Workers (např. maximální délku).

• compatibility_date.

  Pokud jste už dříve používali Pages Functions, nastavte na stejné datum, jaké je nakonfigurované tam. Jinak nastavte aktuální datum.

Tam, kde jste dříve pro Pages konfigurovali „adresář výstupu sestavení“ (buď v Konfigurační soubor Wrangler nebo v Cloudflare dashboard), nyní musíte nastavit assets.directory hodnota pro projekt Worker.

Dříve, s Cloudflare Pages:

{
	"name": "my-pages-project",
	"pages_build_output_dir": "./dist/client/"
}

name = "my-pages-project"
pages_build_output_dir = "./dist/client/"

Nyní s Cloudflare Workers:

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"assets": {
		"directory": "./dist/client/"
	}
}

name = "my-worker"
# Set this to today's date
compatibility_date = "2026-08-28"

[assets]
directory = "./dist/client/"

Pages se automaticky pokusí určit typ nasazeného projektu. Vyhledá přitom 404.html a index.html soubory jako signál toho, zda šlo pravděpodobně o Jednostránková aplikace (SPA) nebo zda by měl vracet vlastní stránky 404.

Ve Workers je toto chování kvůli prevenci náhodné chybné konfigurace explicitní a musí být nastaveno ručně.

Pro Single Page Application (SPA):

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"assets": {
		"directory": "./dist/client/",
		"not_found_handling": "single-page-application"
	}
}

name = "my-worker"
# Set this to today's date
compatibility_date = "2026-08-28"

[assets]
directory = "./dist/client/"
not_found_handling = "single-page-application"

Pro vlastní stránky 404:

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"assets": {
		"directory": "./dist/client/",
		"not_found_handling": "404-page"
	}
}

name = "my-worker"
# Set this to today's date
compatibility_date = "2026-08-28"

[assets]
directory = "./dist/client/"
not_found_handling = "404-page"

Pages automaticky vyloučí některé soubory a složky z nahrávání jako statická aktiva, například node_modules, .DS_Store, a .git. Pokud chcete zabránit i nahrávání těchto souborů do Workers, můžete vytvořit .assetsignore soubor v adresáři statických assetů vašeho projektu.

**/node_modules
**/.DS_Store
**/.git

Pokud používáte fullstack framework postavený na Pages Functions, ujistěte se, že máte aktualizovali jste svůj framework pro cílení na Workers namísto Pages.

Pokud používáte Pages Functions s "advanced mode" _worker.js soubor, nejprve musíte zajistit, že se tento skript nenahraje jako statický asset. Buď přesuňte _worker.js z adresáře se statickými soubory (doporučeno), nebo vytvořit .assetsignore soubor v adresáři statických assetů a zahrnout _worker.js v jeho rámci.

_worker.js

Poté ve svém konfiguračním souboru aktualizujte main pole tak, aby ukazovalo na umístění tohoto skriptu Workeru:

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"main": "./dist/client/_worker.js", // or some other location if you moved the script out of the static asset directory
	"assets": {
		"directory": "./dist/client/"
	}
}

name = "my-worker"
# Set this to today's date
compatibility_date = "2026-08-28"
main = "./dist/client/_worker.js"

[assets]
directory = "./dist/client/"

Pokud používáte Pages Functions s složka functions/, nejprve musíte tyto funkce zkompilovat do jednoho skriptu Workeru pomocí wrangler pages functions build příkazu.

npx wrangler pages functions build --outdir=./dist/worker/

Ačkoli tento příkaz zůstane k dispozici a budete jej moci spustit kdykoli, doporučujeme zvážit použití jiného frameworku, pokud chcete pokračovat v používání směrování založeného na souborech. HonoX ↗ je jednou z oblíbených možností.

Jakmile je skript Workeru zkompilovaný, můžete v konfiguračním souboru aktualizovat main pole tak, aby ukazovalo na umístění, do kterého byl sestaven:

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"main": "./dist/worker/index.js",
	"assets": {
		"directory": "./dist/client/"
	}
}

name = "my-worker"
# Set this to today's date
compatibility_date = "2026-08-28"
main = "./dist/worker/index.js"

[assets]
directory = "./dist/client/"

Pokud jste vytvořili _routes.json soubor ve vašem projektu Pages, nebo použili middleware v Pages Functions musíte věnovat velkou pozornost konfiguraci svého Worker skriptu. Pages by ve výchozím nastavení obsluhovaly vaše Pages Functions přednostně před statickými assety a _routes.json a middleware Pages Functions vám umožňovaly toto chování přizpůsobit.

Workers naopak ve výchozím nastavení obsluhují statická aktiva před vaším skriptem Workeru, pokud jste nenakonfigurovali assets.run_worker_first. Tato možnost je povinná, pokud například před poskytnutím statických souborů provádíte ověřovací kontroly nebo logujete požadavky.

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"main": "./dist/worker/index.js",
	"assets": {
		"directory": "./dist/client/",
		"run_worker_first": true
	}
}

name = "my-worker"
# Set this to today's date
compatibility_date = "2026-08-28"
main = "./dist/worker/index.js"

[assets]
directory = "./dist/client/"
run_worker_first = true

Pokud chcete, můžete začít se skriptem Workeru úplně od začátku a využít všechny funkce Wrangleru a nejnovějšího runtime (například WorkerEntrypoints, Podpora TypeScript, bundling, atd.):

import { WorkerEntrypoint } from "cloudflare:workers";

export default class extends WorkerEntrypoint {
	async fetch(request) {
		return new Response("Hello, world!");
	}
}

import { WorkerEntrypoint } from "cloudflare:workers";

export default class extends WorkerEntrypoint {
	async fetch(request: Request) {
		return new Response("Hello, world!");
	}
}

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"main": "./worker/index.ts",
	"assets": {
		"directory": "./dist/client/"
	}
}

name = "my-worker"
# Set this to today's date
compatibility_date = "2026-08-28"
main = "./worker/index.ts"

[assets]
directory = "./dist/client/"

Pages automaticky poskytuje ASSETS binding pro přístup ke statickým assets z Pages Functions. Ve Workers je název tohoto bindingu upravitelný a musí být nakonfigurován ručně:

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"main": "./worker/index.ts",
	"assets": {
		"directory": "./dist/client/",
		"binding": "ASSETS"
	}
}

name = "my-worker"
# Set this to today's date
compatibility_date = "2026-08-28"
main = "./worker/index.ts"

[assets]
directory = "./dist/client/"
binding = "ASSETS"

Pokud jste si upravili umístění, nebo nastavte compatibility date nebo jakýkoli compatibility flags ve vašem projektu Pages, totéž můžete definovat v konfiguračním souboru Wrangler:

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"compatibility_flags": ["nodejs_compat"],
	"main": "./worker/index.ts",
	"placement": {
		"mode": "smart"
	},
	"assets": {
		"directory": "./dist/client/",
		"binding": "ASSETS"
	}
}

name = "my-worker"
# Set this to today's date
compatibility_date = "2026-08-28"
compatibility_flags = [ "nodejs_compat" ]
main = "./worker/index.ts"

[placement]
mode = "smart"

[assets]
directory = "./dist/client/"
binding = "ASSETS"

Proměnné a vazby lze nastavit v Konfigurační soubor Wrangler a jsou zpřístupněny v prostředí vašeho Workeru (env). Tajné klíče lze nahrát přes Wrangler nebo definovat v Cloudflare dashboardu pro produkce a .dev.vars pro lokální vývoj.

Pokud jste používání Workers Builds, nezapomeňte také tam nakonfigurujte všechny proměnné relevantní pro sestavovací prostředí. Na rozdíl od Pages nesdílí Workers stejnou sadu proměnných pro runtime a build.

Tam, kde jste dříve používali wrangler pages dev a wrangler pages deploy, nyní místo toho použijte wrangler dev a wrangler deploy. Pokud navíc používáte framework postavený na Vite, náš nový Vite plugin vám může nabídnout ještě jednodušší vývojářský zážitek.

Pokud používáte vestavěný CI/CD systém Pages, můžete jej nahradit Workers Builds tak, že nejprve připojení vašeho repozitáře k Workers Builds a poté vypnutí automatického nasazování v projektu Pages.

Pages automaticky vytváří náhledové prostředí pro každý projekt a lze je nakonfigurovat nezávisle.

Chcete-li dosáhnout podobného chování ve Workers, musíte:

1. Zajistěte, že URL náhledů jsou povoleny (ve výchozím nastavení jsou zapnuté).

   {
   	"name": "my-worker",
   	// Set this to today's date
   	"compatibility_date": "2026-08-28",
   	"main": "./worker/index.ts",
   	"assets": {
   		"directory": "./dist/client/"
   	},
   	"preview_urls": true
   }

   name = "my-worker"
   # Set this to today's date
   compatibility_date = "2026-08-28"
   main = "./worker/index.ts"
   preview_urls = true
   
   [assets]
   directory = "./dist/client/"

2. Povolit sestavení pro neprodukční větve ve Workers Builds.

Volitelně můžete také chraňte tyto URL náhledů pomocí Cloudflare Access.

_headers a _redirects soubory jsou ve Workers se statickými prostředky podporovány nativně. Stejně jako u Pages zajistěte, aby tyto soubory byly součástí adresáře se statickými prostředky vašeho projektu.

Tam, kde vám bylo dříve nabízeno pages.dev subdoménu pro váš projekt Pages si nyní můžete nastavit personalizovanou workers.dev subdoménu pro všechny své projekty Worker. Můžete nakonfigurujte tuto subdoménu v Cloudflare dashboardu, a přihlásit se k jejímu použití pomocí workers_dev možnost ve vašem konfiguračním souboru.

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"main": "./worker/index.ts",
	"workers_dev": true
}

name = "my-worker"
# Set this to today's date
compatibility_date = "2026-08-28"
main = "./worker/index.ts"
workers_dev = true

Pokud jsou nameservery vaší domény spravované přes Cloudflare, můžete stejně jako u Pages nakonfigurovat vlastní doména pro váš Worker. Kromě toho můžete také nakonfigurovat trasa pokud chcete, aby váš Worker obsluhoval jen podmnožinu cest.

Jakmile ověříte chování Workeru, budete spokojeni s vývojovými postupy a přesunete veškerý produkční provoz, můžete svůj projekt Pages smazat v Cloudflare dashboardu nebo pomocí Wrangleru:

npx wrangler pages project delete

Můžete přidat následující experimentální prompt ↗ ve vašem preferovaném asistentovi pro psaní kódu (např. Claude Code, Cursor), abyste svůj projekt zkompatibilnili s Workers:

https://developers.cloudflare.com/workers/prompts/pages-to-workers.txt

Můžete také použít Cloudflare Documentation server MCP ↗ ve vašem asistentovi pro psaní kódu, abyste svému LLM poskytli lepší kontext při vývoji s Workers, což zahrnuje tento prompt, když požádáte o migraci z Pages na Workers.

Tato tabulka kompatibility porovnává funkce Workers a Pages. Není-li níže uvedeno jinak, platí, že co funguje v Pages, funguje i ve Workers, a co funguje ve Workers, funguje i v Pages. Chybí vám v tomto seznamu něco? Otevřete pull request ↗ nebo vytvořte GitHub issue ↗.

Legenda
✅: Podporováno
⏳: Již brzy
🟡: Nepodporováno, řešení k dispozici
❌: Nepodporováno