ChunkLoadError и Failed to fetch dynamically imported module
ChunkLoadError в webpack и «Failed to fetch dynamically imported module» в Vite — одна и та же ошибка. Браузер не смог загрузить кусок приложения (чанк), который код подгружает по требованию через import(). Почти всегда она появляется сразу после выкладки: у посетителя открыта вкладка со старой сборкой, он переходит на новую страницу, а чанка старой сборки на сервере уже нет.
Ниже — что значит ошибка в разных браузерах и сборщиках, как её воспроизвести, как исправить и как узнать, сколько посетителей на неё наткнулось.
Что значит ошибка
Современные сборщики делят приложение на чанки, а в имя файла кладут хэш содержимого: assets/Settings-B3xk9.js. Пока код страницы не менялся, имя не меняется. Как только код изменился, у чанка новое имя, а старый файл после выкладки обычно удаляется.
Дальше происходит так:
- Посетитель открыл сайт в 10:00 — загрузился
index-a1b2.jsсо ссылками на чанки этой сборки. - В 10:15 вы выложили новую версию. В папке на сервере теперь
Settings-C7d8.js, аSettings-B3xk9.jsбольше нет. - В 10:20 посетитель нажимает «Настройки». Старый код просит
Settings-B3xk9.js, сервер отвечает 404 — или отдаётindex.htmlвместо скрипта. import()падает, страница не открывается.
Текст ошибки зависит от сборщика и браузера:
| Где | Текст |
|---|---|
| Vite, Chrome | TypeError: Failed to fetch dynamically imported module: https://…/assets/Settings-B3xk9.js |
| Vite, Firefox | TypeError: error loading dynamically imported module |
| Vite, Safari | TypeError: Importing a module script failed. |
| Vite, стили чанка | Error: Unable to preload CSS for /assets/Settings-B3xk9.css |
| webpack | ChunkLoadError: Loading chunk 123 failed. или Loading CSS chunk 123 failed. |
В переводе «Failed to fetch dynamically imported module» — «не удалось загрузить динамически импортируемый модуль». Ошибка не в вашем коде, а в рассинхроне между открытой вкладкой и сервером.
Бывают и другие причины: обрыв сети на мобильном, блокировщик рекламы, CDN, который ещё не получил новые файлы. Если сервер на запрос несуществующего .js отдаёт index.html (обычная настройка SPA), в консоли появится ещё и «Expected a JavaScript module script but the server responded with a MIME type of text/html».
Как воспроизвести ChunkLoadError
Проще всего на vite preview или любом статическом сервере:
npm run build && npx vite preview # откройте сайт, но не заходите на страницу с lazy-компонентом
# поменяйте код этой страницы
npm run build # Vite очищает dist: старые чанки удаленыТеперь в уже открытой вкладке перейдите на страницу с lazy-компонентом — получите «Failed to fetch dynamically imported module». Второй способ — DevTools → Network → правой кнопкой по запросу чанка → «Block request URL» и перезагрузка.
Как исправить: перезагрузка по vite:preloadError
Надёжнее всего перезагрузить страницу: браузер получит свежий index.html и чанки новой сборки. Vite 4.4+ сообщает о неудачной загрузке событием vite:preloadError на window. Важно не зациклиться: если чанка нет и в новой сборке (ошибка в конфигурации CDN), перезагрузка будет повторяться бесконечно.
// main.ts — до запуска приложения
const KEY = 'chunk-reload-at';
window.addEventListener('vite:preloadError', (event) => {
const last = Number(sessionStorage.getItem(KEY) || 0);
if (Date.now() - last < 60_000) return; // уже перезагружали минуту назад — пусть ошибка всплывёт
sessionStorage.setItem(KEY, String(Date.now()));
event.preventDefault(); // Vite не бросит ошибку дальше
window.location.reload();
});В webpack такого события нет. Ошибку видно по error.name === 'ChunkLoadError' — в Error Boundary или в обработчике unhandledrejection, логика та же:
window.addEventListener('unhandledrejection', (event) => {
if (event.reason?.name !== 'ChunkLoadError') return;
const last = Number(sessionStorage.getItem('chunk-reload-at') || 0);
if (Date.now() - last < 60_000) return;
sessionStorage.setItem('chunk-reload-at', String(Date.now()));
window.location.reload();
});Важно. Перезагрузка теряет несохранённое: введённый текст, открытые модальные окна. Если у вас длинные формы, вместо мгновенной перезагрузки покажите плашку «Вышла новая версия — обновите страницу».
Как исправить: хранить старые чанки после выкладки
Перезагрузка лечит симптом. Причину убирает другое: не удалять файлы старой сборки сразу после выкладки. Тогда открытая вкладка спокойно догрузит свой чанк.
- CDN или S3. Загружайте новые файлы рядом со старыми, без удаления (
aws s3 sync dist s3://bucketбез--delete). Старьё чистите правилом жизненного цикла через 1–2 недели. - Docker-образ с nginx. В новом образе старых чанков нет. Можно копировать в образ папку
assetsпредыдущей сборки или отдавать статику с общего тома или CDN, а не из образа. - Сначала чанки, потом index.html. Выкладывайте новые чанки до того, как начнёте отдавать новый
index.html. Иначе посетитель получит страницу, которая ссылается на ещё не загруженные файлы.
Заголовки кеша для index.html
Вторая частая причина — закешированный index.html. Если браузер или CDN держат старую страницу часами, посетитель после выкладки снова и снова получает ссылки на удалённые чанки. Правильная схема: чанки с хэшем кешируются навсегда, index.html — никогда без проверки.
location /assets/ {
add_header Cache-Control "public, max-age=31536000, immutable";
try_files $uri =404; # нет файла — 404, а не index.html
}
location = /index.html {
add_header Cache-Control "no-cache";
}
location / {
try_files $uri /index.html;
}try_files $uri =404 для /assets/ нужен, чтобы на несуществующий чанк приходил честный 404, а не HTML-страница под видом скрипта.
Как исправить: lazy с повтором
Если чанк не загрузился из-за сбоя сети, помогает повтор import() с паузой:
import { lazy, type ComponentType } from 'react';
function lazyWithRetry<T extends ComponentType<any>>(factory: () => Promise<{ default: T }>, retries = 2) {
return lazy(async () => {
for (let attempt = 0; ; attempt++) {
try {
return await factory();
} catch (error) {
if (attempt >= retries) throw error;
await new Promise((r) => setTimeout(r, 500 * (attempt + 1)));
}
}
});
}
const Settings = lazyWithRetry(() => import('./pages/Settings'));Повтор не спасает после выкладки — файла просто нет. Кроме того, некоторые браузеры запоминают неудачный import() того же адреса и не запрашивают его снова. Поэтому повтор — дополнение к перезагрузке и хранению старых чанков, а не замена.
Сколько посетителей наткнулось на ChunkLoadError
В консоли своего браузера вы эту ошибку почти не увидите: она случается у тех, кто держал вкладку открытой во время выкладки. Узнать масштаб можно только мониторингом ошибок в браузерах посетителей.
Пакет @nablops/react (и ядро @nablops/browser) распознаёт такие ошибки сам. Он слушает vite:preloadError, узнаёт тексты из таблицы выше и не загрузившиеся скрипты, modulepreload и стили своего домена. Всё это помечается как «не загрузился чанк после выкладки». В NablOps они собираются в одну ошибку на фронтенд и релиз, независимо от имени чанка. Поэтому выкладка не превращается в десятки записей «Loading chunk 17 failed», «Loading chunk 23 failed».
Ошибка привязана к релизу сборки, которая была открыта у посетителя. На вкладке «Релизы» видно, когда выложена каждая версия и сколько в ней новых ошибок. На странице ошибки — браузеры, системы, страницы и число сессий за 30 дней. Если после выкладки таких ошибок много, значит старые чанки удаляются слишком рано.
Перезагрузку пакет может делать сам:
import * as nabl from '@nablops/react';
nabl.init({
key: 'pk_…',
reloadOnChunkError: true, // перезагрузить страницу, если чанк не нашёлся
});С reloadOnChunkError: true пакет сначала отправляет ошибку, потом перезагружает страницу — не чаще раза в минуту на вкладку, чтобы не зациклиться. Для vite:preloadError он сам вызывает preventDefault(), поэтому свой обработчик из примера выше уже не нужен. По умолчанию опция выключена: пакет только сообщает об ошибке.
Разобрать всплеск после выкладки можно и через ИИ-ассистента: он видит ошибки фронтенда, релизы и сессии.
Что дальше
- Мониторинг ошибок React — как подключить
@nablops/react. - Source maps — релизы и исходный код вместо бандла.
- Сессии и пользователи — что делал посетитель до ошибки.
- Error Boundary в React — экран вместо белой страницы, когда чанк не загрузился.
Первый сервер или стек подключается за пару минут. Бесплатно в раннем доступе.
Нашли неточность или не хватает ответа? Напишите в поддержку