ChunkLoadError после деплоя обычно означает смесь версий. Открытая вкладка получила HTML и manifest выпуска A, а после переключения попросила chunk A у сервера, где остался только выпуск B. Другой вариант: CDN отдал старый HTML, а origin уже удалил названные в нём файлы.

Жёсткая перезагрузка помогает одному пользователю, но не устраняет окно несовместимости. Сначала сохраните конкретный 404 и заголовки; затем восстановите, кто выдал ссылку на файл. Иначе purge может скрыть симптом, а следующий rolling deploy повторит его.

Цепочка запроса указывает владельца старой ссылки

АртефактЧто сравнитьПодозрительный результат
HTML documentAge, cache status, build markerСтарый HTML после cutover
Manifest/runtimeСписок chunk и build idA ссылается на удалённый asset
Chunk requestURL, referer, status, cache404 у части edge/instances
Server instanceImage digest и deployment idВ пуле одновременно разные сборки
CDN originПуть _next/static и assetPrefixCDN смотрит не в тот release
Service workerАктивная версия и cache namesСтарая оболочка продолжает жить

В DevTools включите Preserve log, воспроизведите переход внутри приложения и экспортируйте только технические запросы. Query string, cookies и ответы с пользовательскими данными в тикет не прикладывайте. На сервере достаточно request id, URL asset, status и deployment id.

Хешированный файл и HTML требуют разной политики кеша

Next.js выдаёт действительно immutable assets с длинным Cache-Control, потому что их имена содержат hash. Это безопасно, пока содержимое по такому URL не заменяется и файл не исчезает раньше всех документов, которые на него ссылаются. HTML и данные маршрута имеют другой жизненный цикл: именно они выбирают новую версию assets.

# Идея заголовков, точные правила зависят от платформы
/_next/static/*
  Cache-Control: public, max-age=31536000, immutable

/document-or-route-data
  Cache-Control: no-cache

# no-cache разрешает хранение, но требует валидации перед повторным использованием.
# Не применяйте один год к HTML только потому, что так кешируются chunks.

Перед изменением заголовков измерьте фактический путь через reverse proxy и CDN. Повторное использование одного URL для нового содержимого ломает смысл immutable. А короткий TTL asset-файлов не спасает, если deployment удаляет их мгновенно — браузер всё равно может запросить старое имя из уже открытого документа.

Rolling deploy сохраняет одну версию на весь запрос

  1. Собрать artifact один раз и присвоить ему immutable build/deployment id.
  2. Загрузить новые assets до того, как новый HTML станет доступен.
  3. Запустить все новые instances из того же artifact, не выполняя next build на каждом сервере.
  4. Переключать трафик только после readiness и проверки chunk URLs.
  5. Сохранять assets предыдущего выпуска в течение рассчитанного окна старых вкладок/кеша.
  6. Удалять старый release отдельной задачей после метрики обращений, а не в момент cutover.

Текущее руководство Next.js требует использовать один build на нескольких контейнерах. Для self-hosted multi-instance deployment deploymentId включает защиту от version skew: клиент и сервер сравнивают выпуск, а при несовпадении навигация становится полной загрузкой. Это уменьшает смешивание, но не освобождает от корректной доступности static assets.

assetPrefix меняет маршрут, а не состав релиза

Если static files живут на отдельном CDN, assetPrefix заставляет Next.js строить URL для `/_next/static` через этот origin. В CDN загружают содержимое `.next/static` как `_next/static`; серверный код и остальную `.next` публиковать туда не следует. Проверьте, что префикс одинаков в build и runtime, а CDN origin видит нужную директорию версии.

  • Не смешивайте assets staging и production в одном изменяемом префиксе.
  • Не перезаписывайте существующий хешированный файл другим содержимым.
  • Не удаляйте предыдущую директорию до окончания переходного окна.
  • Не собирайте разные build id на каждом pod одного релиза.
  • Не кешируйте пользовательский HTML как общедоступный без корректного key.
  • Не делайте бесконечный reload-loop при ошибке загрузки chunk.

Service worker проверяется отдельной веткой

Если сайт использует service worker, он может отдавать старую app shell или runtime из собственного Cache Storage, даже когда CDN уже корректен. Запишите active worker script URL, его версию и cache names. Обновление должно активировать новую версию по предусмотренному жизненному циклу и не смешивать HTML одного release с chunks другого.

Не вызывайте Clear-Site-Data или массовую очистку caches без понимания последствий: можно удалить offline-данные и авторизационное состояние. Сначала воспроизведите проблему в обычной вкладке, затем с bypass service worker. Разница подтверждает направление диагностики.

Проверка релиза имитирует живую старую вкладку

СценарийОжидаемый результатМетрика
Новая вкладка после cutoverHTML и chunks новой версии0 asset 404
Старая вкладка делает переходСовместимая навигация или hard reloadОшибки по build id
Запрос попал в старый podВерсия согласована правилами rolloutInstance/deployment id
CDN edge с холодным кешемAsset получен с originStatus и cache result
Service worker старой версииКонтролируемое обновлениеWorker/cache version

Релиз готов, когда новая и заранее открытая вкладки проходят несколько переходов без 404, каждый ответ помечен ожидаемым deployment id, а метрика missing assets остаётся нулевой в течение переходного окна. Для разбора нужны release timeline, image digest, build/deployment id, CDN headers, пример chunk URL и схема хранения прошлых assets.

Проверенные источники