DevOps / CI/CD

Будет ли Next.js 16.1 PPR автоматически использовать chunked encoding на Cloudflare Workers?

Будет ли Next.js 16.1 PPR автоматически использовать chunked encoding на Cloudflare Workers?

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

Быстрый вывод: Cloudflare Workers поддерживает потоковые ответы, а для ответа с телом ReadableStream платформа документирует использование chunked encoding. Это подтверждает механизм передачи, но не доказывает, что он вызывает сбой Next.js 16.1 PPR. Сначала проверьте конкретный путь запроса, согласованный протокол и факт завершения тела; меняйте приложение или конфигурацию только по результатам сопоставимого теста.

Статья предназначена для инженеров, которые проверяют поведение Next.js 16.1 PPR на Cloudflare Workers, и специалистов, отвечающих за наблюдаемость HTTP-ответов.
Техническим руководителям она поможет оценить, нужен ли общий удалённый рабочий стол для воспроизведения проблемы; такой Mac не заменяет среду выполнения Workers.

Подтверждённый механизм и недоказанная причина

Документация Cloudflare описывает потоки Workers на основе ReadableStream и указывает, что передача такого тела ответа использует chunked encoding. Это платформенное поведение. Оно не означает, что любой ответ Next.js обязательно передаётся одинаково на каждом участке пути: на итоговую картину влияют протокол соединения, промежуточные прокси, адаптер и код, который формирует Response. См. описание потоков в Workers и документацию Response.

Важно отделять три уровня доказательств:

  • Подтверждённое свойство платформы. Workers умеет возвращать потоковые ответы; для ReadableStream в описанном Cloudflare сценарии применяется chunked encoding.
  • Наблюдение конкретного запроса. Браузер получил определённый статус, набор заголовков, протокол и тело, которое либо завершилось, либо осталось неполным.
  • Причина поломки. Чтобы связать неполный ответ именно с PPR, требуется воспроизводимый тест, в котором меняется только проверяемое условие.

Само наличие Transfer-Encoding: chunked в ответе не доказывает, что поток был оборван. И отсутствие этого заголовка само по себе не опровергает потоковую передачу. Заголовок относится к правилам HTTP/1.1; RFC 9112 описывает chunked transfer coding для сообщений HTTP/1.1. Поэтому сначала зафиксируйте фактически согласованный протокол, а уже затем интерпретируйте заголовки. Заголовки ответа также не показывают, обработал ли браузер все фрагменты и завершилось ли тело без ошибки.

Для инженерной проверки полезно вести журнал отдельно от вывода о причине. Записывайте URL и метод запроса, время, статус, протокол, значимые заголовки, наличие кэширования или сжатия и результат чтения тела. Если однажды зафиксирован незавершённый ответ, это свидетельство о конкретной попытке, но не об универсальном ограничении Workers или PPR.

Один и тот же симптом может появиться на разных этапах: при формировании потока приложением, его преобразовании адаптером или передаче до клиента. Пока эти этапы не разделены тестом, диагноз «виноват chunked encoding» преждевременен.

Прямой запрос и пределы наблюдения

Начните с запроса к развёрнутой странице без промежуточного ручного воспроизведения ответа. В инструментах разработчика браузера выберите сам документ, а не только запросы к данным или скриптам. Зафиксируйте статус, протокол соединения и заголовки. Дождитесь окончания загрузки и отметьте, завершилось ли чтение тела, появился ли текст ошибки и соответствует ли фактический HTML ожидаемой странице.

При необходимости повторите запрос через curl, указав URL и сохранив заголовки вместе с телом. Сравнивайте результат только при одинаковых условиях: тот же адрес, метод, заголовки авторизации, cookies и параметры кэширования. Запрос из браузера и команда в терминале могут получить разные ответы, если отличаются cookies, протокол, клиентское сжатие или маршрут через промежуточный слой.

Разбор заголовков должен отвечать на ограниченный набор вопросов:

  • Статус: кто именно вернул ответ и каким он выглядит для клиента? Сам код статуса не всегда раскрывает источник.
  • Протокол: по какой версии HTTP пришёл ответ? Это влияет на то, какие признаки передачи тела ожидаются.
  • Заголовки: видны ли сведения о кэшировании, сжатии или кодировании передачи? Их отсутствие не равнозначно отсутствию потока.
  • Тело: получен ли полный документ, включая динамический участок, или клиент прекратил чтение раньше?

У ReadableStream нет обязанности оставлять в конечном ответе браузера диагностически удобную подпись, которая однозначно устанавливает происхождение потока. Кроме того, промежуточная система может изменить заголовки или способ доставки. Поэтому заголовки отвечают на вопрос «что наблюдал клиент», а не автоматически на вопрос «где возникла ошибка».

Если ответ имеет статус 502 или 504, сохраните тело ответа и заголовки, а затем сопоставьте их с журналами Worker и приложения. Cloudflare отдельно описывает возможные источники таких ошибок и способы различить сбой на стороне Cloudflare и ответ от исходного сервера в руководстве по ошибкам 502 и 504. Не объявляйте любой ответ 502 ошибкой edge-платформы: приложение тоже может сформировать ответ с таким статусом. И наоборот, страница ошибки с привычным видом не является достаточным доказательством, что её сформировало приложение.

Адаптер и пользовательский Worker

Прямой запрос показывает результат для клиента, но не объясняет внутренний путь тела ответа. Следующий сценарий — проверить код между приложением и браузером. Это может быть адаптер, пользовательский Worker или обёртка, которая получает ответ Next.js и создаёт новый Response.

Изучите фактическую реализацию именно развёрнутой версии. Найдите места, где код читает тело, вызывает text() или arrayBuffer(), преобразует поток, копирует ответ либо создаёт новый объект ответа. Сам факт создания Response ещё не означает, что тело буферизуется; решает способ передачи тела и то, какие операции выполняются до возврата результата. По этой же причине нельзя без проверки объявлять конкретный адаптер причиной остановки потока.

Для каждого потенциального преобразования ответьте на практические вопросы:

  • Передаётся ли исходный ReadableStream дальше или сначала полностью читается?
  • Ожидает ли обработчик завершения чтения до формирования ответа?
  • Меняются ли заголовки, статус и тело при создании нового Response?
  • Есть ли ветвление для кэширования, сжатия, ошибок или конкретных маршрутов?
  • Одинаково ли работает путь для PPR-страницы и для контрольной страницы без PPR?

Затем повторите тот же запрос с минимальным изменением: обходите необязательную обёртку, если это возможно в вашей схеме, либо временно направьте тестовый маршрут через проверяемый слой без дополнительных преобразований. Не меняйте одновременно адаптер, настройки сжатия и логику страницы. Иначе улучшение или ухудшение результата нельзя будет связать с конкретным изменением.

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

Кэш и сжатие как отдельные переменные

Третий сценарий — сопоставить запросы при разных состояниях кэша и сжатия. Сначала проверьте путь без изменения кода: повторите запрос к одной странице с одинаковыми параметрами и запишите заголовки, указывающие на статус кэша. Важны не предположения о том, что «этот URL должен кэшироваться», а фактический результат для каждого запроса. Для интерпретации кэширования Cloudflare предлагает руководство по исследованию некэшируемых ответов.

Отдельно проверьте сжатие. Сопоставьте запросы с одинаковым маршрутом и условиями, изменив только возможность согласовать сжатый ответ, если это безопасно в тестовой среде. Записывайте заголовки ответа и результат чтения тела. Документация Cloudflare объясняет поведение сжатия контента, но не утверждает, что сжатие автоматически вызывает обрыв ответа PPR.

У такого сравнения есть ограничения. Ответ из кэша может отличаться от свежего ответа по содержимому и заголовкам. Клиентская поддержка сжатия тоже меняет представление тела, которое наблюдается в инструментах. Если одновременно очистить кэш, изменить заголовки запроса и отключить сжатие, тест перестанет отделять одну переменную от другой.

Практический протокол такой: сохраните исходный запрос, выполните повтор без изменения условий, затем проверьте кэшируемый и некэшируемый варианты, а сжатие исследуйте отдельной парой. Для каждой попытки указывайте, что изменилось и завершилось ли тело. Если симптом появляется только в одном режиме, это сужает область поиска, но ещё не устанавливает причинность: например, кэш может изменить маршрут ответа, а не сломать поток.

Настройка PPR в Next.js 16

Для конфигурации важно различать актуальные параметры и старое экспериментальное имя. В руководстве по переходу на Next.js 16 указано, что PPR включается через настройку cacheComponents; экспериментальный флаг и соответствующие параметры PPR удалены. Проверьте описание изменений в официальном руководстве Next.js 16.

Не переносите старую настройку experimental_ppr в новую конфигурацию, предполагая, что она по-прежнему управляет PPR в Next.js 16. Сверьте конфигурацию приложения с руководством для вашей версии, затем проверьте фактическую сборку и развёрнутый артефакт. Старый флаг в конфигурации и новый способ включения функции — разные вещи; наличие одного не подтверждает, что приложение запущено с ожидаемым поведением.

При этом изменение настройки PPR не должно быть первым способом проверить HTTP-транспорт. Если страница отвечает неполно, сравнение должно показывать, отличается ли результат именно при включённом PPR, а не просто после произвольной правки конфигурации. Убедитесь, что обе сборки используют один маршрут, один адаптер и одинаковую схему запросов. Только так разницу можно связать с PPR с большей уверенностью.

Воспроизводимое сравнение PPR и контрольного маршрута

Для сопоставления подготовьте две версии одного и того же маршрута: с PPR и без него. Сохраните одинаковыми данные, проверку авторизации, адаптер, настройки кэширования и сжатия, а также способ вызова страницы. Если динамическая часть зависит от внешнего сервиса, обеспечьте одинаковые условия её получения или используйте контролируемый источник данных. Иначе задержка внешнего сервиса смешается с проверкой передачи ответа.

Проведите серии запросов по одному и тому же сценарию. Для каждой попытки сохраняйте:

  • идентификатор сборки и конфигурацию PPR;
  • URL, метод и значимые заголовки запроса;
  • статус и протокол, показанные клиенту;
  • заголовки ответа, включая кэширование, сжатие и кодирование передачи, если они присутствуют;
  • факт завершения тела и состояние динамического фрагмента;
  • журналы приложения и Worker, относящиеся к этому запросу.

Не считайте единичное отличие доказательством. Повторите тест после перезапуска или повторного развёртывания, если это необходимо для исключения устаревшего состояния. Сравнивайте результаты одной пары условий, прежде чем переходить к следующей. Если PPR и контрольная версия одинаково обрываются, это ослабляет гипотезу о специфической проблеме PPR. Если сбой устойчиво возникает только в одной версии, это основание исследовать соответствующий участок, но не автоматическое доказательство вины chunked encoding.

Критерии выбора следующего шага

  • Если обе версии завершают тело и динамическая часть отображается, то не меняйте PPR из-за самого факта применения chunked encoding.
  • Если PPR-сборка повторяемо не завершает тело, а контрольная версия при тех же условиях работает, то используйте отключение PPR как временный обходной путь и повторите тест с тем же запросом. Зафиксируйте результаты до и после изменения.
  • Если обе версии проявляют одинаковый сбой, то не связывайте его с PPR только по этому сравнению. Проверьте общий участок: обработчик, адаптер, внешний источник данных или маршрут ответа.
  • Если результат меняется только при кэше или сжатии, то исследуйте соответствующее преобразование отдельно и сохраните исходную конфигурацию для повторения.
  • Если наблюдается 502 или 504 без достаточных данных о происхождении, то сопоставьте ответ с журналами и рекомендациями Cloudflare, прежде чем менять логику приложения.

Перед изменением конфигурации проверьте условия выбора:

  • [ ] Один и тот же запрос к PPR-маршруту воспроизводит незавершённое тело.
  • [ ] Контрольный маршрут проверен с теми же данными, адаптером, кэшем, сжатием и способом вызова.
  • [ ] Сохранены протокол, статус, заголовки и результат чтения тела для обеих версий.
  • [ ] Изменялось только одно условие за раз; эффект изменения повторно проверен.
  • [ ] Проверено, не возвращает ли 502 или 504 само приложение и что показывают журналы Worker.

Если все пункты подтверждены и сбой остаётся только на PPR-маршруте, временный откат обоснован как мера снижения риска. Если ключевые данные отсутствуют или обе версии ведут себя одинаково, сначала продолжайте локализацию — откат в таком случае не устанавливает и не устраняет доказанную причину. Возвращайте PPR после проверки исправления или обходного пути тем же набором условий.

Такой откат — временное инженерное решение, а не утверждение, что PPR несовместим с Workers. После изменения повторите тот же набор запросов, сохраните данные до и после и сообщите команде, что именно изменилось. Это позволяет отделить результат временной меры от подтверждённого исправления.

Заключение, пригодное для повторной проверки

Итоговый отчёт лучше разделить на подтверждённые свойства, наблюдения и открытые гипотезы. Например: «Документация Cloudflare описывает потоковый ответ ReadableStream и chunked encoding. В развёрнутой сборке с PPR при таких условиях тело завершилось не полностью. В контрольной сборке при тех же условиях тело завершилось». Такая формулировка сообщает установленное и не приписывает платформе причину, которую тест ещё не доказал.

Для каждого наблюдения сохраняйте команды или шаги воспроизведения, конфигурацию сборки и копии заголовков. Не заменяйте их заключением вроде «Workers обрезает динамическую часть»: подобное утверждение требует повторяемого свидетельства и привязки к конкретному пути развёртывания. Если обнаружено ограничение адаптера или платформы, добавьте ссылку на описание соответствующей версии либо приложите минимальный воспроизводимый пример. Если такого подтверждения нет, укажите, что гипотеза остаётся непроверенной.

При изменении документации Next.js, Workers или адаптера перепроверьте вывод на новой конфигурации. Повторное подтверждение особенно важно, если меняется способ формирования Response, пересматриваются настройки PPR или появляется новый воспроизводимый случай. Официальная документация фиксирует заявленное поведение компонентов; только фактический тест подтверждает, что именно происходит в конкретной цепочке доставки.

Если текущий способ совместной работы опирается на локальные машины, отдельные ручные развёртывания и пересылку неполных логов, у него есть реальные издержки: сложнее повторить идентичную сборку, согласовать конфигурацию и сохранить общий журнал наблюдений. Удалённый Mac от ProxyMac может дать команде общий рабочий узел для подготовки сборки и совместного воспроизведения. Но он не заменяет Cloudflare Workers и не проверяет поведение их runtime за вас. Состав вариантов удалённой работы можно посмотреть на странице ProxyMac, а вопросы доступа и настройки — в справочном разделе. Для проверки HTTP-ответа итоговым критерием всё равно остаются одинаковые запросы к развёрнутой цепочке и сохранённые результаты.

Проверяйте веб-приложения на удалённом Mac

ProxyMac предоставляет выделенный облачный Mac mini M4 для разработки, сборки и тестирования ваших проектов.
Подключайтесь по SSH, через VNC или браузер и проверяйте поведение приложения в удалённой среде.