Webpack: Loading chunk failed の原因と解決策

概要

Webpackの動的インポートでチャンクファイルの読み込みに失敗した場合に発生するエラーです。

エラーメッセージ

ChunkLoadError: Loading chunk 0 failed.
(error: https://example.com/static/js/0.chunk.js)

原因

ファイル不存在: デプロイ後に古いチャンクにアクセス
パス誤り: publicPathの設定が不正
ネットワークエラー: 一時的な接続問題
キャッシュ問題: CDNやブラウザキャッシュ

解決策

1. エラーハンドリング

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
// リトライ付き動的インポート
async function loadComponent(componentName) {
  try {
    return await import(`./components/${componentName}`);
  } catch (error) {
    if (error.name === 'ChunkLoadError') {
      // リロードで最新版を取得
      window.location.reload();
    }
    throw error;
  }
}

2. React.lazyでのエラー境界

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
import { lazy, Suspense } from 'react';
import ErrorBoundary from './ErrorBoundary';

const LazyComponent = lazy(() => import('./LazyComponent'));

function App() {
  return (
    <ErrorBoundary fallback={<ReloadPrompt />}>
      <Suspense fallback={<Loading />}>
        <LazyComponent />
      </Suspense>
    </ErrorBoundary>
  );
}

3. Webpack設定

1
2
3
4
5
6
7
8
// webpack.config.js
module.exports = {
  output: {
    filename: '[name].[contenthash].js',
    chunkFilename: '[name].[contenthash].chunk.js',
    publicPath: '/'
  }
};

4. Service Workerでキャッシュ管理

1
2
3
4
// 新しいビルドでSWを更新
self.addEventListener('install', (event) => {
  self.skipWaiting();
});

よくある間違い

ハッシュなしのファイル名でキャッシュ問題
publicPathの末尾スラッシュ忘れ

概要

エラーメッセージ

原因

解決策

1. エラーハンドリング

2. React.lazyでのエラー境界

3. Webpack設定

4. Service Workerでキャッシュ管理

よくある間違い

Webpack の他のエラー