Vite 504 エラー (Outdated Optimize Dep) の解決方法

問題の概要

React と Vite を使用した開発中に、js-big-decimal などのパッケージをインストール後、以下のエラーが発生するケースがあります。

504 (Outdated Optimize Dep)

このエラーは、ブラウザコンソールに表示され、アプリケーションが正常に読み込まれなくなります。

エラーが発生する典型的な環境

• React プロジェクトで Vite をビルドツールとして使用
• 新しいパッケージをインストールした直後
• 開発サーバーを再起動せずに依存関係を更新

根本原因

このエラーは Vite の依存関係最適化プロセスに関連しています。

Vite は起動時に依存パッケージを事前バンドルするため、依存関係が変更された状態で既存のキャッシュを使用すると互換性問題が発生します。

効果的な解決策

1. Vite キャッシュのクリア (推奨)

最も安全で効果的な方法です：

# Viteのキャッシュディレクトリを削除
rm -rf node_modules/.vite

# npm ユーザーの場合
npm cache clean --force && npm i

# Yarn ユーザーの場合
yarn cache clean && yarn

注意

プロジェクトの実行中は操作を行わないでください。必ず開発サーバーを停止してから実行します。

2. 問題のあるパッケージを最適化除外する

特定のパッケージで発生する場合の対処法：

import { defineConfig } from "vite";

export default defineConfig({
  optimizeDeps: {
    exclude: ['js-big-decimal'] // エラー発生パッケージを指定
  },
  plugins: [react()]
});

変更後は必ず開発サーバーを再起動してください。

3. ブラウザキャッシュの強制クリア

ブラウザ側のキャッシュが原因の場合：

• Chrome: Ctrl + Shift + R (Windows/Linux) または Cmd + Shift + R (Mac)
• Firefox: Ctrl + F5 または Cmd + Shift + R
• Safari: Option + Cmd + E → 開発メニューからキャッシュクリア

4. 依存関係の完全再インストール

より根本的な解決が必要な場合：

# 依存関係の完全クリーンアップ
rm -rf node_modules package-lock.json
npm install
npm run dev

その他の対処法

開発サーバーの強制再起動

vite.config.js のスクリプトを変更：

"scripts": {
  "dev": "vite --force", // --force オプション追加
  "build": "vite build",
  "preview": "vite preview"
}

複数プロジェクトでのキャッシュ競合解消

同じディレクトリで複数プロジェクトを操作する場合：

export default defineConfig({
  cacheDir: './node_modules/.vite_project_a', // プロジェクトごとに一意の名前
})

環境設定の確認

以下の項目を確認してください：

{
  "engines": {
    "node": ">=18" // 正しいNodeバージョンを指定
  }
}

予防策

1. 依存関係を変更したら必ず開発サーバーを再起動
2. 長すぎるディレクトリパスを避ける
3. 開発中は異なるNodeバージョンを使用しない

まとめ

504 (Outdated Optimize Dep) エラーは主に Vite の依存関係キャッシュの問題から発生します。ほとんどのケースで .vite ディレクトリの削除と依存関係の再インストールで解決できます。問題が特定のパッケージに依存する場合は optimizeDeps.exclude の設定が有効です。これらの手順は副作用が少なく、開発フローを迅速に回復させる最も確実な方法です。