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

Перенос с Pages на Workers

Полноценные full-stack приложения, включая статические файлы фронтенда и API бэкенда, а также страницы с серверным рендерингом (SSR), можно развёртывать с помощью Cloudflare Workers.

Подобно Pages, запросы к статическим ресурсам в Workers бесплатны, и Pages Functions вызовы тарифицируются по той же ставке, что и Workers, поэтому можно ожидать аналогичную структуру затрат.

В отличие от Pages, у Workers значительно более широкий набор доступных функций (включая Durable Objects, Cron Triggers и более полную Observability). Полный список доступен по адресу нижняя часть этой страницы.

Перенос проекта с Cloudflare Pages на Cloudflare Workers обычно не вызывает сложностей. Ниже перечислены основные шаги, которые потребуется выполнить для переноса проекта.

Если ваш проект Pages использует популярный фреймворк, для большинства фреймворков уже есть адаптеры для Cloudflare Workers. Замените любые адаптеры, специфичные для Pages, на эквиваленты для Workers и следуйте указаниям, которые они предоставляют.

Если в вашем проекте его ещё нет, создайте конфигурационный файл Wrangler (либо wrangler.jsonc, wrangler.json или wrangler.toml) в корне вашего проекта. Два обязательных поля:

• name

  Укажите имя Worker, в который нужно выполнить развёртывание. Оно может совпадать с именем существующего проекта Pages, если соответствует ограничениям на имена Workers (например, по максимальной длине).

• compatibility_date.

  Если вы уже использовали Pages Functions, укажите ту же дату, что настроена там. В противном случае укажите текущую дату.

Там, где раньше вы настраивали «build output directory» для Pages (либо в конфигурационный файл Wrangler или в панель управления Cloudflare), теперь необходимо задать assets.directory значение для проекта Worker.

Раньше, с Cloudflare Pages:

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

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

Теперь с помощью 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 автоматически пытается определить тип развернутого вами проекта. Для этого выполняется поиск 404.html и index.html файлы как признак того, что проект, вероятно, является Одностраничное приложение (SPA) или должен ли он отдавать пользовательские страницы 404.

В Workers, чтобы предотвратить случайную неверную настройку, это поведение задаётся явно и необходимо настроить вручную.

Для одностраничного приложения (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"

Для пользовательских страниц 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 автоматически исключает некоторые файлы и папки из загрузки в качестве статических ресурсов, например node_modules, .DS_Store, а также .git. Если вы также хотите избежать загрузки этих файлов в Workers, можно создать .assetsignore файл в каталоге статических ресурсов вашего проекта.

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

Если вы используете full-stack фреймворк на основе Pages Functions, убедитесь, что у вас есть обновили фреймворк для использования Workers вместо Pages.

Если вы используете Pages Functions с «расширенным режимом» _worker.js файл, сначала убедитесь, что этот скрипт не загружается как статический ресурс. Либо переместите _worker.js из каталога статических ресурсов (рекомендуется), либо создать .assetsignore файл в каталоге статических ресурсов и включает _worker.js внутри него.

_worker.js

Затем обновите в конфигурационном файле main поле так, чтобы оно указывало на расположение скрипта этого Worker:

{
	"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/"

Если вы используете Pages Functions с папка с functions/, сначала вам нужно скомпилировать эти функции в единый скрипт Worker с помощью wrangler pages functions build команда.

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

Эта команда останется доступной для запуска в любое время, но если вы хотите и дальше использовать файловую маршрутизацию, рекомендуем рассмотреть другой фреймворк. HonoX ↗ один из популярных вариантов.

После компиляции скрипта Worker можно обновить main поле так, чтобы оно указывало на каталог, в который собирается проект:

{
	"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/"

Если вы являетесь автором _routes.json файл в вашем проекте Pages, или использовали промежуточное ПО в Pages Functions необходимо уделять пристальное внимание конфигурации скрипта Worker. По умолчанию Pages обслуживает Pages Functions раньше статических ресурсов и _routes.json и middleware Pages Functions позволяли настраивать это поведение.

Workers, напротив, по умолчанию отдают статические ресурсы раньше скрипта Worker, если только вы не настроили assets.run_worker_first. Этот параметр обязателен, например, если вы выполняете проверки аутентификации или логирование запросов перед отдачей статических файлов.

{
	"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

При желании вы можете начать новый скрипт Worker с нуля и воспользоваться всеми возможностями Wrangler и последней версии runtime (например, WorkerEntrypoints, Поддержка TypeScript, объединение, и т. д.):

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 автоматически предоставляет ASSETS привязка для доступа к статическим ресурсам из Pages Functions. В Workers имя этого binding можно задать самостоятельно, и настраивать его нужно вручную:

{
	"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"

Если вы настраивали размещение, либо задайте дата совместимости или любой флаги совместимости в вашем проекте Pages, вы можете задать то же самое в конфигурационном файле 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"

Переменные и привязки можно задать в конфигурационный файл Wrangler и становятся доступны в окружении вашего Worker (env). Секреты можно загрузить через Wrangler или определить в Cloudflare dashboard для продакшен и .dev.vars для локальной разработки.

Если вы с использованием Workers Builds, убедитесь, что вы также настройте там все переменные, относящиеся к среде сборки. В отличие от Pages, Workers не использует тот же набор переменных времени выполнения и времени сборки.

Там, где раньше вы использовали wrangler pages dev и wrangler pages deploy, теперь вместо этого используйте wrangler dev и wrangler deploy. Кроме того, если вы используете фреймворк на основе Vite, наш новый плагин Vite может предложить ещё более простой процесс разработки.

Если вы используете встроенную систему CI/CD в Pages, ее можно заменить на Workers Builds, сначала подключение вашего репозитория к Workers Builds и затем отключение автоматических развёртываний в проекте Pages.

Pages автоматически создает среду предварительного просмотра для каждого проекта, и ее можно настроить отдельно.

Чтобы получить аналогичный опыт в Workers, необходимо:

1. Убедитесь URL-адреса предпросмотра включены (по умолчанию они включены).

   {
   	"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. Включить сборки непроизводственных веток в Workers Builds.

При необходимости можно также защитите эти URL-адреса предпросмотра с помощью Cloudflare Access.

_headers и _redirects файлы нативно поддерживаются в Workers со статическими ресурсами. Убедитесь, что, как и в случае с Pages, эти файлы включены в каталог статических ресурсов вашего проекта.

Там, где раньше вам предлагался pages.dev поддомен для вашего проекта Pages, теперь вы можете настроить персонализированный workers.dev поддомен для всех ваших проектов Worker. Вы можете настройте этот поддомен в панели управления Cloudflare, и включить её использование с workers_dev параметр в вашем конфигурационном файле.

{
	"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

Если серверы имён вашего домена управляются Cloudflare, вы можете, как и в Pages, настроить пользовательский домен для вашего Worker. Кроме того, вы можете настроить маршрут если вы хотите, чтобы Worker обслуживал только некоторое подмножество путей.

После проверки поведения Worker, когда вас устроят рабочие процессы разработки и весь боевой трафик будет перенесен, можно удалить проект Pages в панели управления Cloudflare или с помощью Wrangler:

npx wrangler pages project delete

Можно добавить следующее экспериментальный промпт ↗ в предпочитаемом вами ассистенте для написания кода (например, Claude Code, Cursor), чтобы сделать ваш проект совместимым с Workers:

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

Также можно использовать документацию Cloudflare MCP-сервер ↗ в вашем ассистенте для написания кода, чтобы предоставить вашей LLM больше контекста при разработке с Workers. Это включает данную подсказку, когда вы просите выполнить миграцию с Pages на Workers.

Эта таблица совместимости сравнивает возможности Workers и Pages. Если не указано иное, всё, что работает в Pages, работает и в Workers, и наоборот. Кажется, что в списке чего-то не хватает? Откройте pull request ↗ или создать issue на GitHub ↗.

Легенда
✅: поддерживается
⏳: скоро
🟡: не поддерживается, есть обходное решение
❌: не поддерживается