Webpack 5『Persistent Caching』を極め尽くせ：filesystemキャッシュで大規模プロジェクトのビルド時間を80%削減する実務アーキテクチャ
テックリードの皆さん、日々の開発において「Webpackのビルド待ち時間」にどれだけのエンジニアリング資源をドブに捨てているか意識したことはあるだろうか。数千ファイルを超える巨大なモノリス、あるいは複雑なモジュール federation を採用したマイクロフロントエンド構成において、`webpack` コマンドを実行してからバンドルが完了するまでの数分間は、開発者の「フロー状態」を容赦なく破壊する。
ネット上の浅い記事では「Webpack 5に上げたら速くなりますよ」としか書かれていない。しかし、デフォルト設定のままでは、CI環境やローカルの特定条件下でキャッシュが効かず、毎回フルビルドが走る地獄から抜け出せない。
今回は、Webpack 5の真髄である `cache: { type: ‘filesystem’ }` を極限までチューニングし、大規模プロジェクトのビルド時間を 最大80%削減 するための実践的アーキテクチャを解説する。単なるオプションの列挙ではなく、内部で何が起きているのかというデータフローの理解から、CI/CDでのキャッシュ共有戦略まで、プロの現場で即座に使える知見を叩き込む。
—
1. なぜ「filesystemキャッシュ」で爆速になるのか？（内部動作の理解）
Webpack 4までのメモリキャッシュ（`cache: true`）は、プロセスが終了すれば消え去る儚いものだった。そのため、CLIを再起動するたびに、全てのファイルをパースし、AST（抽象構文木）を生成し直すという重労働が強制されていた。
Webpack 5で導入されたファイルシステムキャッシュは、一度ビルドしたモジュールのコンパイル結果、依存関係グラフ、最適化されたチャンク情報を ハードディスク（デフォルトでは `node_modules/.cache/webpack`）にシリアライズして永続化 する。
キャッシュ無効化（Invalidation）のメカニズム
キャッシュにおいて最も難しい問題は「いつキャッシュを捨てるべきか」だ。Webpack 5は、以下の要素を複合的に監視してキャッシュの有効性を判定している。
1. ファイルのコンテンツハッシュ: ファイルの内容が変わっていれば無効化。
2. 依存関係の変化: `import` や `require` のパスが変わった場合。
3. 環境変数と設定ファイル: `webpack.config.js` 自体の変更、またはビルド時に参照された環境変数（`process.env.NODE_ENV` など）の差異。
4. loaderのバージョン: 使用しているloader（`babel-loader`, `ts-loader` 等）のバージョンアップ。
この判定機構が極めて優秀であるため、手動で `rimraf node_modules/.cache` を叩く必要はもはや存在しない。正しく設定されていれば、変更された差分モジュールのみが再コンパイルされ、残りはディスクから一瞬でロードされる。
—
2. 実務で真価を発揮する `webpack.config.js` ベストプラクティス構成
プロダクション環境および開発環境で耐えうる、極限まで最適化された設定ファイルの全容を提示する。各プロパティの意味をコードコメントとして刻み込んでいるため、そのままプロジェクトに移植してほしい。
const path = require(‘path’);
const HtmlWebpackPlugin = require(‘html-webpack-plugin’);
const { WebpackManifestPlugin } = require(‘webpack-manifest-plugin’);
module.exports = (env, argv) => {
const isProduction = argv.mode === ‘production’;
return {
// 大規模プロジェクトの高速化には欠かせないソースマップの選択
// 開発時は速度重視、本番はデバッグ性を考慮
devtool: isProduction ? ‘source-map’ : ‘eval-cheap-module-source-map’,
entry: ‘./src/index.tsx’,
output: {
path: path.resolve(__dirname, ‘dist’),
// キャッシュバスティングのためにコンテンツハッシュを付与
filename: isProduction ? ‘js/[name].[contenthash:8].js’ : ‘js/[name].js’,
chunkFilename: isProduction ? ‘js/[name].[contenthash:8].chunk.js’ : ‘js/[name].chunk.js’,
clean: true, // ビルド前にdistディレクトリを自動クリーンアップ
},
cache: {
// メモリではなくファイルシステムにキャッシュを永続化
type: ‘filesystem’,
// キャッシュの保存先を明示的に指定（デフォルトもここだが明記を推奨）
cacheDirectory: path.resolve(__dirname, ‘.cache/webpack’),
// 開発環境と本番環境でキャッシュが混ざらないよう名前空間を分離
name: `${argv.mode}-${process.env.CI_JOB_NAME || ‘local’}`,
// キャッシュの世代管理：依存パッケージのバージョンアップ時に自動でキャッシュを無効化
version: require(‘./package.json’).dependencies,
// filesystemキャッシュのシリアライズにtarを使わない高速なアルゴリズムを指定
compression: ‘gzip’,
// キャッシュが無効化されるトリガーとなるファイルの追加
// 例: 設定ファイルやbabelの設定が変わったら強制的にキャッシュ破棄
buildDependencies: {
config: [
__filename,
path.resolve(__dirname, ‘tsconfig.json’),
path.resolve(__dirname, ‘.babelrc.js’),
],
},
// メモリ上に保持するキャッシュの最大容量（デフォルトは自動だが調整可能）
maxMemoryGenerations: 10,
},
module: {
rules: [
{
test: /\.[jt]sx?$/,
exclude: /node_modules/,
use: {
loader: ‘babel-loader’,
options: {
// babel-loader自体にもキャッシュを有効化させ、二重で高速化
cacheDirectory: true,
cacheCompression: false, // 圧縮はWebpack側に任せるためここではオフ
},
},
},
// CSS, 画像等のローダー設定が続く…
],
},
plugins: [
new HtmlWebpackPlugin({
template: ‘./public/index.html’,
}),
new WebpackManifestPlugin(),
],
optimization: {
// モジュールIDの決定論的付与：ビルドごとにハッシュが変わるのを防ぎ、キャッシュ効率を最大化
moduleIds: ‘deterministic’,
chunkIds: ‘deterministic’,
// 共通モジュールのスプリッティング
splitChunks: {
chunks: ‘all’,
cacheGroups: {
vendor: {
test: /[\\/]node_modules[\\/]/,
name: ‘vendors’,
chunks: ‘all’,
},
},
},
},
};
};
—
3. CI環境におけるキャッシュの再利用戦略（GitHub Actions編）
ローカル環境では爆速になったとしても、GitHub ActionsなどのCI環境で毎回クリーンなコンテナからビルドが開始される場合、キャッシュの恩恵を受けられず、ビルド時間が逆に遅くなる（ファイルを書き出すオーバーヘッドが増えるため）という罠がある。
CI環境でファイルシステムキャッシュを極限まで活かすには、「前回のビルド成果物（`.cache/webpack`）をワークフロー間で永続化・復元する」 仕組みが必要不可欠だ。
以下のGitHub Actionsワークフロー設定例を見てほしい。
name: Production Build
on:
push:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: 1. リポジトリのチェックアウト
uses: actions/checkout@v4
- name: 2. Node.js環境のセットアップ
uses: actions/setup-node@v4
with:
node-version: ’20’
cache: ‘npm’ # npmの依存関係キャッシュ
- name: 3. 依存関係のインストール
run: npm ci
- name: 4. Webpack Persistent Cacheの復元
uses: actions/cache@v4
with:
path: .cache/webpack
# package-lock.json と webpack.config.js のハッシュをキーにする
# これにより、依存関係や設定が変わった瞬間のみキャッシュがパージされる
key: webpack-cache-${{ runner.os }}-${{ hashFiles(‘package-lock.json’, ‘webpack.config.js’) }}
restore-keys: |
webpack-cache-${{ runner.os }}-
- name: 5. プロダクションビルドの実行
run: npm run build
env:
NODE_ENV: production
- name: 6. ビルド成果物のアップロード
uses: actions/upload-artifact@v4
with:
name: production-dist
path: dist/
このYAMLがもたらす実務上の利益
- `hashFiles(‘package-lock.json’, ‘webpack.config.js’)`: 依存関係やビルドロジックに一切の変更がない限り、前回のキャッシュが完璧にヒットする。
- `restore-keys`: 完全一致するキーが見つからない場合でも、直近のキャッシュをフォールバックとして復元し、差分ビルドによって爆速を維持する。
—
4. 開発スピードを劇的に高めるプロの技：隠れたショートカットと神プラグイン
設定の最適化と並行して、開発者の手元（Local）での開発体験（DX）を極限まで高めるためのツールチェインとテクニックを共有する。
絶対に入れるべき神プラグイン
1. `speed-measure-webpack-plugin` (SMP)
- 「どのローダーやプラグインがビルド時間を食いつぶしているか」を完全に可視化する。
- ただし、Webpack 5のキャッシュ機能と同時に使うと競合して正しく計測できない場合があるため、パフォーマンス測定専用のスクリプト（`npm run analyze:speed` など）を別枠で用意して一時的に有効化するのがプロの作法だ。
2. `fork-ts-checker-webpack-plugin`
- TypeScriptの型チェックを別プロセス（別スレッド）で非同期実行する。
- `ts-loader` 自体で型チェックを行うとメインのビルドスレッドがブロックされるが、これを使うことでビルド速度はそのままに、IDEと同等の型安全性を担保できる。
現場で役立つ開発用CLIショートカット
日々の業務で無駄な打鍵を減らし、開発フローを加速させる `package.json` のスクリプト設計：
{
“scripts”: {
“dev”: “webpack serve –mode development –config webpack.config.js”,
“build”: “webpack –mode production –config webpack.config.js”,
“build:profile”: “cross-env MEASURE_SPEED=true webpack –mode production”,
“clean:cache”: “rimraf .cache/webpack dist”
}
}
- 万が一、キャッシュが破損した（あるいは挙動が怪しい）場合に備えて、`npm run clean:cache` を即座に叩けるようにチーム全体で共通認識を持っておくこと。
—
5. チーム開発で事故らないための共有化ルール
最後に、この強力なキャッシュ機能運用する上で、チーム開発で絶対に守るべき鉄則を提示する。
1. `.cache/` は絶対にGitにコミットしない
- `.gitignore` に `.cache/` を必ず追加すること。これを誤ってコミットすると、リポジトリの肥大化を招き、チームメンバー間でキャッシュの競合や権限エラー（EACCES）が頻発する原因になる。
2. Node.jsのバージョンを `engines` で完全に固定する
- ファイルシステムキャッシュのバイナリシリアライズは、V8エンジンやNode.jsの内部バイナリ構造に強く依存している。チーム内でNode.jsのマイナーバージョンすらバラバラだと、キャッシュの互換性エラーや予期せぬビルド崩壊を引き起こす。`.nvmrc` や `package.json` の `engines` を厳格に運用せよ。
まとめ
Webpack 5の `filesystem` キャッシュは、正しく設計・運用すれば、もはや「遅いビルドツール」というWebpackの悪評を過去のものにするほどのポテンシャルを秘めている。
今回紹介した設定とCIキャッシュ戦略をプロジェクトに導入すれば、ローカルでのHMR（Hot Module Replacement）の立ち上がり、そしてCIでのプルリクエストビルドは劇的なまでに高速化される。待ち時間に奪われていた貴重な思考の時間をエンジニアリングの本質へとフックさせ、チーム全体の生産性を圧倒的な高みへと引き上げてほしい。