ChunkLoadError после деплоя обычно означает смесь версий. Открытая вкладка получила HTML и manifest выпуска A, а после переключения попросила chunk A у сервера, где остался только выпуск B. Другой вариант: CDN отдал старый HTML, а origin уже удалил названные в нём файлы.
Жёсткая перезагрузка помогает одному пользователю, но не устраняет окно несовместимости. Сначала сохраните конкретный 404 и заголовки; затем восстановите, кто выдал ссылку на файл. Иначе purge может скрыть симптом, а следующий rolling deploy повторит его.
Цепочка запроса указывает владельца старой ссылки
| Артефакт | Что сравнить | Подозрительный результат |
|---|---|---|
| HTML document | Age, cache status, build marker | Старый HTML после cutover |
| Manifest/runtime | Список chunk и build id | A ссылается на удалённый asset |
| Chunk request | URL, referer, status, cache | 404 у части edge/instances |
| Server instance | Image digest и deployment id | В пуле одновременно разные сборки |
| CDN origin | Путь _next/static и assetPrefix | CDN смотрит не в тот 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 сохраняет одну версию на весь запрос
- Собрать artifact один раз и присвоить ему immutable build/deployment id.
- Загрузить новые assets до того, как новый HTML станет доступен.
- Запустить все новые instances из того же artifact, не выполняя next build на каждом сервере.
- Переключать трафик только после readiness и проверки chunk URLs.
- Сохранять assets предыдущего выпуска в течение рассчитанного окна старых вкладок/кеша.
- Удалять старый 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. Разница подтверждает направление диагностики.
Проверка релиза имитирует живую старую вкладку
| Сценарий | Ожидаемый результат | Метрика |
|---|---|---|
| Новая вкладка после cutover | HTML и chunks новой версии | 0 asset 404 |
| Старая вкладка делает переход | Совместимая навигация или hard reload | Ошибки по build id |
| Запрос попал в старый pod | Версия согласована правилами rollout | Instance/deployment id |
| CDN edge с холодным кешем | Asset получен с origin | Status и cache result |
| Service worker старой версии | Контролируемое обновление | Worker/cache version |
Релиз готов, когда новая и заранее открытая вкладки проходят несколько переходов без 404, каждый ответ помечен ожидаемым deployment id, а метрика missing assets остаётся нулевой в течение переходного окна. Для разбора нужны release timeline, image digest, build/deployment id, CDN headers, пример chunk URL и схема хранения прошлых assets.