← Cloudflare Workers / workers / framework-guides / web-apps

Next.js

Используйте vinext для создания или переноса приложения Next.js и развёртывания его в Cloudflare Workers.

Cloudflare рекомендует vinext ↗ как стандартный способ запуска приложений Next.js на Cloudflare Workers. vinext предлагает две отправные точки: создать новое приложение, готовое к работе с Workers, с помощью create-vinext-app, либо добавьте vinext в существующее приложение Next.js 16 с помощью одной неразрушающей vinext init (ваш существующий next dev продолжает работать). В любом случае специальный шаблон Cloudflare вам не понадобится.

Уже используете OpenNext? См. другие пути развёртывания Next.js.

Что такое Next.js?

Next.js ↗ это React ↗ фреймворк для создания full-stack приложений.

Next.js поддерживает серверный рендеринг, клиентский рендеринг, статическую генерацию, React Server Components, Server Actions, обработчики маршрутов и middleware.

Что такое vinext?

vinext ↗ представляет собой плагин Vite, который заново реализует API Next.js. Вы можете сохранить существующий app/, pages/, next.config.js, а также public/ каталоги при использовании набора инструментов Vite.

vinext находится в бета-версии. Прежде чем внедрять его в приложении, уже работающем в продакшене, запустите проверку совместимости из каталога проекта и ознакомьтесь с панель совместимости vinext ↗.

npx vinext check

Поддерживаемые возможности

vinext поддерживает большинство часто используемых функций Next.js на Cloudflare Workers:

Возможность	поддержка vinext	Примечания
App Router	Поддерживается	Включает макеты, обработчики маршрутов, метаданные и маршруты loading, error и not-found.
Pages Router	Поддерживается	Включает `getStaticProps`, `getStaticPaths`, а также `getServerSideProps`.
React Server Components	Поддерживается	Использует поддержку React Server Components в Vite.
Server Actions	Поддерживается	Работает с формами и серверными мутациями.
Серверный рендеринг	Поддерживается	Включает потоковый рендеринг.
Статическая генерация и статический экспорт	Поддерживается	Используйте `output: "export"` для статического экспорта.
Incremental Static Regeneration (ISR)	Поддерживается	Использует модель кеширования stale-while-revalidate, чтобы Workers могли отдавать кешированный контент, обновляя его в фоновом режиме. См. асинхронная ревалидация.
Промежуточное ПО и прокси-маршруты	Поддерживается	Включает `middleware.ts` и `proxy.ts`.
`next/*` импорты	В основном поддерживается	Ознакомьтесь с панелью совместимости, чтобы узнать подробности на уровне модулей.
Привязки Cloudflare	Поддерживается	Используйте `cloudflare:workers` в серверных компонентах, обработчиках маршрутов и серверных действиях.
Оптимизация изображений	Частично поддерживается	Оптимизация изображений Cloudflare доступна во время обработки запроса.

Подробные результаты совместимости см. в совместимость vinext ↗.

Выберите способ настройки

Большинство проектов на Next.js могут начинаться с одного и того же процесса: откройте приложение Next.js, проверьте совместимость, добавьте vinext, а затем разверните его в Workers.

Используйте Добавление vinext с помощью агента если вы хотите, чтобы агент проверил проект и применил миграцию.
Используйте Добавление vinext через CLI если вам нужна прямая, воспроизводимая настройка через командную строку.
Используйте Создайте проект, готовый для работы с Cloudflare если хотите создать каркас нового проекта, уже настроенного для Workers.

Добавление vinext с помощью агента

Используйте vinext Agent Skill, если хотите, чтобы агент кодирования проверил ваш проект Next.js, выполнил проверки совместимости, обновил конфигурацию и запустил сервер разработки vinext.

Откройте проект Next.js.

Используйте существующий проект или создайте новый с помощью удобного вам способа настройки Next.js.
Установите Agent Skill для vinext.
npx skills add cloudflare/vinext
Отправьте промпт своему агенту.

В своём агенте для написания кода выполните следующий запрос:
```
migrate this project to vinext
```
Skill выполняет проверки совместимости vinext, применяет миграцию и отмечает проблемы, требующие ручного вмешательства.
Разработка с vinext.

Запустите сервер разработки vinext.
npm run dev:vinext
Собирайте с помощью vinext.

Соберите продакшен-сборку с помощью vinext.
npm run build:vinext
Развертывание в Workers.

Развертывание с помощью команды vinext Cloudflare deploy.
npx @vinext/cloudflare deploy

Добавление vinext через CLI

Используйте vinext init если вам нужна прямая настройка через командную строку. Миграция не разрушительна: существующая настройка Next.js продолжает работать вместе с vinext, пока вы тестируете развёртывание в Cloudflare Workers.

Откройте проект Next.js.

Используйте существующий проект или создайте новый с помощью удобного вам способа настройки Next.js.
Проверьте совместимость.

Запустите проверку совместимости vinext из каталога вашего проекта Next.js.
npx vinext check
Прежде чем продолжить, просмотрите все обнаруженные проблемы совместимости.
Инициализируйте vinext.

Запустите инициализатор vinext и при появлении запроса выберите Cloudflare Workers в качестве цели развёртывания.
npx vinext init
vinext init устанавливает зависимости vinext и Vite, добавляет скрипты vinext, генерирует конфигурацию Vite и создаёт конфигурацию Cloudflare Workers.
Разработка с vinext.

Запустите сервер разработки vinext.
npm run dev:vinext
Собирайте с помощью vinext.

Соберите продакшен-сборку с помощью vinext.
npm run build:vinext
Развертывание в Workers.

Развертывание с помощью команды vinext Cloudflare deploy.
npx @vinext/cloudflare deploy

Создайте проект, готовый для работы с Cloudflare

Используйте create-cloudflare CLI (C3), если хотите создать каркас нового проекта Next.js, уже настроенного для Cloudflare Workers.

Создайте новый проект с помощью C3.
npm create cloudflare@latest -- my-next-app --framework=next
Поведение команды

C3 создаёт новый проект Next.js, настраивает vinext для Cloudflare Workers, устанавливает необходимые зависимости и предлагает развернуть приложение.
Разработка с vinext.

Перейдите в каталог проекта и запустите локальный сервер разработки.
npm run dev
Соберите приложение.

Выполните сгенерированный скрипт сборки перед развёртыванием или тестированием продакшен-сборки.
npm run build
Разверните ваш проект.

Разверните ваш проект в *.workers.dev поддомен или пользовательский домен.
npm run deploy

Доступ к привязкам Cloudflare

В приложениях vinext, развёрнутых на Workers, используйте cloudflare:workers для доступа к bindings из серверных компонентов, Route Handlers и Server Actions. Определите bindings в конфигурации Wrangler, затем сгенерируйте типы с помощью wrangler types.

Например, можно импортировать env от cloudflare:workers в серверном коде приложения для доступа к D1, R2, KV, Durable Objects, Workers AI, Queues, Vectorize и другим привязкам.

Используйте другой способ развёртывания Next.js

vinext является рекомендованным способом развёртывания приложений Next.js на Cloudflare Workers, однако в документации также описаны другие способы развёртывания:

Путь	Когда использовать
Адаптер OpenNext	Вы поддерживаете существующее приложение на OpenNext, которое пока не может перейти на vinext из-за несовместимости.
Статический Next.js на Pages	Ваше приложение представляет собой статический экспорт, и вы хотите развернуть его именно на Cloudflare Pages.