← Cloudflare Workers / workers / framework-guides

Развертывание существующего проекта

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

Когда вы выполняете wrangler deploy или wrangler setup в каталоге проекта без файла конфигурации Wrangler, Wrangler выполнит следующее:

1. Определение фреймворка - анализирует ваш проект, чтобы определить используемый фреймворк
2. Запрос подтверждения - Показывает обнаруженные настройки и просит подтвердить их перед внесением изменений
3. Установка адаптеров - Устанавливает необходимые адаптеры Cloudflare для вашего фреймворка
4. Генерация конфигурации - Создаёт wrangler.jsonc файл с соответствующими настройками
5. Обновите package.json - добавляет полезные скрипты, такие как deploy, preview, а также cf-typegen
6. Настройка git - добавляет специфичные для Wrangler записи в .gitignore

Автоматическая настройка поддерживает следующие фреймворки:

Автоматическая настройка может также работать для других проектов, например SPA на React или Vue. Попробуйте выполнить wrangler deploy или wrangler setup чтобы проверить, обнаружен ли ваш проект.

При запуске автоматической настройки могут быть созданы или изменены следующие файлы:

Создаётся новый файл конфигурации Wrangler с настройками, подходящими для вашего фреймворка:

{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "my-project",
	"main": "dist/_worker.js/index.js",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"compatibility_flags": ["nodejs_compat"],
	"assets": {
		"binding": "ASSETS",
		"directory": "dist",
	},
	"observability": {
		"enabled": true,
	},
}

"$schema" = "node_modules/wrangler/config-schema.json"
name = "my-project"
main = "dist/_worker.js/index.js"
# Set this to today's date
compatibility_date = "2026-08-28"
compatibility_flags = [ "nodejs_compat" ]

[assets]
binding = "ASSETS"
directory = "dist"

[observability]
enabled = true

Точная конфигурация зависит от используемого фреймворка.

Новые скрипты добавляются в ваш package.json:

{
	"scripts": {
		"deploy": "npm run build && wrangler deploy",
		"preview": "npm run build && wrangler dev",
		"cf-typegen": "wrangler types"
	}
}

Добавляются специфичные для Wrangler записи:

# wrangler files
.wrangler
.dev.vars*
!.dev.vars.example

Для фреймворков, которые создают файлы worker в выходном каталоге, .assetsignore файл создается, чтобы исключить их из загрузки статических ресурсов:

_worker.js
_routes.json

Чтобы развернуть существующий проект, выполните wrangler deploy в каталоге вашего проекта:

npx wrangler deploy

Wrangler определит используемый вами фреймворк, покажет конфигурацию, которую собирается применить, и попросит вас подтвердить действия перед внесением изменений и развёртыванием.

Чтобы настроить проект без развертывания, используйте wrangler setup:

npx wrangler setup

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

Чтобы увидеть, какие изменения будут внесены, без фактического изменения файлов:

npx wrangler setup --dry-run

В результате выводится сводка конфигурации, которая была бы сгенерирована.

Чтобы пропустить запросы на подтверждение, используйте --yes флаг:

npx wrangler deploy --yes

Это автоматически применяет конфигурацию с разумными значениями по умолчанию. Это удобно в средах CI/CD или когда вы хотите принять обнаруженные настройки без их проверки.

Когда вы импортируете репозиторий GitHub или GitLab через Cloudflare dashboard, autoconfig запускается в неинтерактивном режиме. Если в вашем репозитории нет файла конфигурации Wrangler, Workers Builds создаст pull request с необходимой конфигурацией.

PR включает все описанные выше изменения конфигурации. Создается предварительное развертывание, чтобы вы могли протестировать изменения перед слиянием. После слияния проект готов к развертыванию.

Подробнее см. в Автоматическое создание pull request.

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

Также проект можно настроить вручную, следуя руководствам для конкретных фреймворков в Руководства по фреймворкам.

Для проектов Next.js автоматическая настройка использует vinext в качестве стандартного пути развёртывания для Cloudflare Workers. Сгенерированная конфигурация добавляет зависимости vinext и Vite, создаёт конфигурацию Cloudflare Workers и добавляет скрипты пакета для разработки, сборки и развёртывания.

vinext поддерживает функции кэширования Next.js, такие как Incremental Static Regeneration (ISR), "use cache", а также unstable_cache. Для production-приложений настройте сгенерированный проект Workers с бэкендом кэша, который требуется вашему приложению. Подробнее см. в кэширование vinext ↗.

Если вместо vinext вам нужен адаптер OpenNext, настройте его вручную, следуя Руководство по адаптеру OpenNext.

Когда вы импортируете репозиторий через Workers Builds в панели управления Cloudflare, автоматическая настройка завершится ошибкой, если ваш проект содержит несколько фреймворков. Чтобы решить эту проблему, задайте корневой каталог на путь, содержащий только один фреймворк. Для monorepo обратитесь к настройка монорепозитория.

При выполнении wrangler deploy или wrangler setup локально, Wrangler предложит выбрать фреймворк, если будет обнаружено несколько поддерживаемых фреймворков.

Если ваш фреймворк не обнаружен, убедитесь, что ваш package.json включает этот фреймворк в качестве зависимости.

Если файл конфигурации Wrangler уже существует, автоматическая настройка не выполняется. Чтобы перенастроить проект, удалите существующий файл конфигурации и выполните wrangler deploy или wrangler setup снова.

Поддержка monorepo и рабочих пространств npm/yarn/pnpm пока ограничена. Wrangler анализирует каталог проекта, из которого запущена команда, но не обнаруживает зависимости, установленные в корне рабочего пространства. Из-за этого определение фреймворка может завершиться неудачей, если фреймворк указан как зависимость в корневом package.json а не в package.json.

Если вы столкнулись с проблемами, сообщите о них в Репозиторий Wrangler на GitHub ↗.