12k
All articles

Как исправить ошибку «Failed to Fetch Dynamically Imported Module»

Исправьте ошибки Vite Failed to fetch dynamically imported module. Определите рассинхронизацию версий, неверные пути, HTML-ответы и сбои сети; сохраните старые файлы и настройте безопасную перезагрузку.

OpenReplay Team
OpenReplay Team
Как исправить ошибку «Failed to Fetch Dynamically Imported Module»

Ошибка «Failed to fetch dynamically imported module» означает, что браузеру не удалось загрузить JavaScript-чанк, запрошенный через import(). В продакшене причина обычно одна: новый деплой удалил чанк, который всё ещё нужен уже открытой вкладке.

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

В статье разобраны механизм ошибки при деплое, три последовательно дополняющих друг друга исправления (сохранение ассетов, обработчик перезагрузки и защита от зацикливания), более редкие причины с тем же сообщением и таблица для вкладки Network, которая помогает их различить.

Ключевые выводы

  • Самая частая причина ошибки «Failed to fetch dynamically imported module» — рассинхронизация версий (version skew): открытая вкладка с предыдущим деплоем запрашивает ленивый чанк по хешированному имени файла, которого на сервере уже нет.
  • Если отдавать index.html с заголовком Cache-Control: no-cache и сохранять ассеты предыдущего деплоя, большинство сбоев из-за рассинхронизации прекращается ещё до выполнения какого-либо клиентского кода.
  • Событие vite:preloadError в Vite позволяет перезагрузить страницу при неудачной загрузке чанка, но обработчику нужна защита на основе временной метки в sessionStorage, иначе перезагрузки могут стать бесконечными.
  • Если упавший запрос .js возвращает 200 с Content-Type: text/html, проблема в fallback-настройках сервера или CDN, а не в рассинхронизации версий.
  • Повторная попытка динамического импорта не исправит рассинхронизацию версий: файла, на который ссылается старая сборка, больше нет.

Почему деплой ломает открытые вкладки?

В руководстве по устранению неполадок Vite названы три причины ошибки TypeError: Failed to fetch dynamically imported module: рассинхронизация версий, плохое сетевое соединение и блокировка запросов браузерными расширениями. Всплеск после релиза даёт именно рассинхронизация версий.

Последовательность событий такая. Пользователь загружает index.html из сборки A, который ссылается на чанки вроде assets/Settings-a1b2c3.js. Вы деплоите сборку B, и хеши содержимого меняются. Во вкладке пользователя всё ещё работает сборка A. При переходе на ленивый маршрут браузер запрашивает Settings-a1b2c3.js, получает 404, и импорт завершается отклонением промиса:

TypeError: Failed to fetch dynamically imported module: https://example.com/assets/Settings-a1b2c3.js

Это формулировка Chromium. В других браузерах тот же сбой описывается иначе, поэтому группируйте ошибки в трекере по причине, а не по точному тексту.

Локально воспроизвести ошибку почти никогда не удаётся: при свежей загрузке страницы HTML и чанки всегда берутся из одной сборки. Сбой возникает только во вкладке, которая загрузила старую сборку до деплоя, а ленивый маршрут запросила после него. К ошибке Vite «Failed to resolve import» это тоже отношения не имеет: та ошибка связана с разрешением путей на этапе сборки, а эта возникает во время выполнения.

Исправление 1: сохраняйте старые ассеты и ревалидируйте HTML

Самое дешёвое решение проблемы рассинхронизации — на сервере: сохраняйте чанки предыдущей сборки и отдавайте HTML с Cache-Control: no-cache. Если чанки сборки A остаются доступными после выкатки сборки B, старые вкладки продолжают работать. В разделе об обработке ошибок загрузки документации Vite отмечается, что многие хостинги удаляют ассеты предыдущего деплоя, и рекомендуется отдавать HTML с Cache-Control: no-cache.

Если отдавать index.html с Cache-Control: no-cache, браузер будет ревалидировать HTML при каждой загрузке. Тогда после перезагрузки страница получит имена чанков новой сборки, а не удалённых. С хешированными ассетами ситуация обратная: их URL меняется при каждом изменении содержимого, поэтому для них можно безопасно задать большой max-age с директивой immutable, описанной на MDN.

location = /index.html {
  add_header Cache-Control "no-cache";
}

location /assets/ {
  add_header Cache-Control "public, max-age=31536000, immutable";
  try_files $uri =404;
}

location / {
  try_files $uri $uri/ /index.html;
}

Делайте деплои аддитивными: загружайте новую папку assets/ рядом со старыми файлами, а устаревшие удаляйте по расписанию. Сколько их хранить — решать вам. Срок должен быть достаточным, чтобы пережить вкладки, которые ваши пользователи реально держат открытыми.

Исправление 2: однократная перезагрузка по vite:preloadError

На клиенте Vite генерирует на window событие vite:preloadError, если динамический импорт не удалось загрузить, и перезагрузка страницы из этого обработчика устраняет последствия рассинхронизации версий. Хранение ассетов на сервере помогает, но рано или поздно старые чанки всё равно удаляются. Исходная ошибка доступна в event.payload, а вызов event.preventDefault() не даёт Vite её выбросить. В руководстве по сборке предлагается перезагружать страницу именно из этого обработчика.

При перезагрузке загружается актуальный index.html, который ссылается на чанки сборки B. Это исправляет рассинхронизацию. Повторная попытка импорта — нет, потому что файла, на который указывает сборка A, на сервере больше нет. Помогает только загрузка нового HTML. (Повтор на месте помогает лишь при кратковременных сетевых сбоях. Раньше спецификация HTML предписывала кешировать неудачные загрузки модулей; whatwg/html#10327 это изменил, но поддержка различается — см. таблицу совместимости import() на MDN.)

Исправление 3: защита от бесконечных перезагрузок

Обработчику перезагрузки по vite:preloadError нужна защита от зацикливания. Если устарел сам HTML (например, потому что edge-кеш игнорирует no-cache) или чанк отсутствует в обеих сборках, перезагрузка завершится тем же сбоем, и страница будет перезагружаться бесконечно. В некоторых фреймворках такое восстановление встроено, поэтому сначала загляните в документацию своего фреймворка. Например, Nuxt по умолчанию перезагружает страницу при ошибках загрузки чанков: его вспомогательная функция перезагрузки записывает каждую перезагрузку в sessionStorage и игнорирует повторные запросы в течение 10 секунд. Для чистого Vite с React, Vue или Svelte добавьте следующий код в точку входа:

// src/main.js
const RELOAD_KEY = 'chunk-reload-at';
const RELOAD_WINDOW_MS = 10_000; // tunable, not a standard value

function lastReload() {
  try {
    return Number(sessionStorage.getItem(RELOAD_KEY)) || 0;
  } catch {
    return 0;
  }
}

function markReload() {
  try {
    sessionStorage.setItem(RELOAD_KEY, String(Date.now()));
    return true;
  } catch {
    return false; // storage unavailable: don't risk a loop
  }
}

window.addEventListener('vite:preloadError', (event) => {
  console.error(event.payload); // send to your error tracker instead

  const recentlyReloaded = Date.now() - lastReload() < RELOAD_WINDOW_MS;
  if (!recentlyReloaded && markReload()) {
    event.preventDefault();
    window.location.reload();
  }
  // Otherwise let the error reach the app's error boundary.
});

Обработчик перезагружает страницу сразу, поэтому не важно, чем завершится импорт после preventDefault(). Если перезагрузка уже произошла в пределах заданного окна, обработчик не подавляет ошибку. Она всплывает дальше, и вместо приложения error boundary показывает сообщение:

import React from 'react';

class ChunkErrorBoundary extends React.Component {
  state = { failed: false };
  static getDerivedStateFromError() {
    return { failed: true };
  }
  render() {
    if (!this.state.failed) return this.props.children;
    return (
      <div role="alert">
        <p>A new version is available.</p>
        <button onClick={() => window.location.reload()}>Refresh</button>
      </div>
    );
  }
}

Кнопку Refresh нажимает сам пользователь, поэтому защите не нужно её блокировать. Во Vue и Svelte есть аналогичные хуки обработки ошибок. В любом случае обрабатывайте отклонённый промис на уровне маршрута или error boundary: в документации Vite не уточняется, проходит ли через это событие каждый неудачный динамический импорт.

Более редкие причины той же ошибки

Ошибку «Failed to fetch dynamically imported module» также вызывают проблемы с путями, сервером и клиентом, никак не связанные с деплоем. Такие сбои обычно затрагивают и сессии, начатые уже после релиза.

  • Неверный путь base. Если в URL упавшего чанка нет префикса пути, по которому развёрнуто приложение, причина в опции base конфигурации Vite, а не в устаревшем деплое. Укажите в ней путь развёртывания или передайте --base при сборке, как описано в документации Vite о публичном базовом пути:

    // vite.config.js — app served from https://example.com/app/
    // without base: /assets/c-x1y2.js     (404)
    // with base:    /app/assets/c-x1y2.js
    import { defineConfig } from 'vite';
    
    export default defineConfig({ base: '/app/' });
  • HTML вместо .js. Fallback для SPA или rewrite-правило CDN отвечает на запрос неизвестного чанка содержимым index.html. Браузер отклоняет такой ответ как модуль, потому что его MIME-тип не соответствует JavaScript. Исключите /assets/ из fallback, чтобы для отсутствующих файлов возвращался настоящий 404, как в блоке nginx выше.

  • Блокировщики рекламы. Расширения часто блокируют файлы, в именах которых встречаются слова вроде «ad» или «track». Vite предлагает переименовывать чанки через build.rolldownOptions.output.chunkFileNames. В Vite 7 и более ранних версиях опция называется build.rollupOptions; Vite 8 по-прежнему принимает её как устаревший алиас.

    build: { rolldownOptions: { output: { chunkFileNames: 'assets/c-[hash].js' } } }
  • Обрывы сети. Они возникают периодически, затрагивают файлы с любыми именами и не имеют HTTP-статуса. Перезагрузка с защитой покрывает и этот случай.

Как определить, какая именно причина у вас?

Откройте вкладку Network, найдите упавший запрос чанка и проверьте две вещи: код ответа и Content-Type. Вместе они указывают на причину.

Что показывает упавший запрос чанкаВероятная причинаРешение
404, хешированное имя файла из старой сборкиРассинхронизация версийИсправления 1–3
200, Content-Type: text/htmlFallback для SPA или rewrite в CDNВозвращать настоящие 404 для /assets/
404, в URL нет подпути развёртыванияНеверный baseЗадать base
Заблокирован, в имени файла есть «рекламные» словаРасширениеПереименовать через chunkFileNames
Сбой без статуса, возникает периодическиСетьПерезагрузка с защитой

Обычно воспроизвести сбой самостоятельно не получается, поэтому определить причину помогут данные из продакшена. Записывайте идентификатор релиза вместе с каждой ошибкой — это часть грамотных практик логирования ошибок. Трекинг ошибок в сочетании с записью сессий (session replay) показывает, сосредоточены ли сбои сразу после деплоя в сессиях, начатых до него, — это характерный признак рассинхронизации. Запись сессии также покажет, сработала ли однократная перезагрузка и восстановилось ли приложение. Как и ошибки «ResizeObserver loop completed», это шумная ошибка продакшена, которую нужно классифицировать, а не заглушать.

Устранение первопричины

«Failed to fetch dynamically imported module» — обычно проблема деплоя, которая проявляется в клиентском коде. Начните с сервера: сохраняйте предыдущие ассеты, отдавайте index.html с no-cache и следите, чтобы запросы к /assets/ никогда не уходили в fallback на HTML. Затем в качестве страховки добавьте обработчик vite:preloadError с защитой от зацикливания и error boundary. Прежде чем менять конфигурацию, откройте вкладку Network на упавшем запросе и подтвердите причину по коду ответа и типу содержимого.

Часто задаваемые вопросы

Это та же проблема, что и ChunkLoadError в webpack?

Да, первопричина та же, но ошибка возникает в другом месте. Webpack загружает чанки через собственный рантайм, который отклоняет промис с ChunkLoadError и сообщением вроде 'Loading chunk 42 failed'. Продакшен-сборки Vite используют нативный import(), поэтому вы видите собственную ошибку браузера. Серверные исправления одинаковы для обоих: сохраняйте старые ассеты и ревалидируйте HTML. Событие vite:preloadError существует только в Vite.

Может ли service worker или предзагрузка чанков предотвратить ошибки рассинхронизации версий?

Оба подхода указаны в руководстве по устранению неполадок Vite как способы смягчить проблему. Service worker, который заранее загружает и кеширует все ассеты, сохраняет чанки старой сборки доступными для уже открытых вкладок даже после их удаления с сервера. Предзагрузка динамических чанков получает их до того, как деплой успеет их удалить, но не помогает, если браузер закешировал HTML из-за заголовков Cache-Control.

Почему эта ошибка появляется на dev-сервере Vite, где никакого деплоя нет?

На dev-сервере обычная причина — браузерное расширение. В руководстве по устранению неполадок Vite отмечается, что расширения, например блокировщики рекламы, могут мешать клиенту Vite отправлять запросы на dev-сервер, что приводит к той же ошибке. Чтобы убедиться в этом, отключите расширения для localhost или проверьте работу в чистом профиле браузера. В режиме разработки рассинхронизация версий невозможна, потому что сборку под открытой вкладкой ничто не подменяет.

DevTools for the frontend

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers.

Star on GitHub12k

We use cookies to improve your experience. By using our site, you accept cookies.