Vite + React 起動時のエラー解決

問題の説明

Vite + Reactプロジェクトでnpm run devコマンドを実行した際、以下のエラーが発生するケースがあります：

✘ [ERROR] Expected identifier but found "import"

  (define name):1:0:
    1 │ import.meta.dirname
      ╵ ~~~~~~

エラーメッセージはimport.meta.dirname、import.meta.filename、import.meta.url関連の構文エラーを示し、最終的にビルド失敗となります：

failed to load config from /path/to/vite.config.js
error when starting dev server:
Error: Build failed with 3 errors:

この問題はプロジェクトのフォルダ構造に関係なく発生します（例：frontend/backendの分離構成でも発生）。

根本原因

このエラーの主原因は：

1. esbuildバージョン0.24.1に導入された変更
2. Viteが内部的にimport.meta構文を処理する方法との非互換性
3. Viteバージョン6.0.4以下での発現（最新版では修正済み）

注意

環境によっては自動インストールされるesbuild@0.24.1がエラーのトリガーになります。

解決策

🚀 推奨解決策: Viteを最新版に更新

最も安全かつ恒久的な解決法はViteを6.0.5以上に更新することです：

npm install vite@latest

バージョン確認：

npm list vite
# vite@6.1.0 など6.0.5以上であることを確認

6.0.5以降のViteでは内部でesbuildを安定版に固定する修正が施されています。

⏪ 代替策：esbuildのバージョンダウングレード

即時対応が必要な場合、依存関係にesbuild@0.24.0を明示的に追加：

npm install --save-dev esbuild@0.24.0

package.jsonに直接記載する場合：

"devDependencies": {
  "esbuild": "0.24.0",
  "vite": "^6.0.4"
}

🔒 依存関係の固定（追加対策）

プロジェクト全体で特定バージョンを強制する方法：

npm

// package.json
{
  "overrides": {
    "esbuild": "0.24.0"
  }
}

yarn

// package.json
{
  "resolutions": {
    "esbuild": "0.24.0"
  }
}

pnpm

// package.json
{
  "pnpm": {
    "overrides": {
      "esbuild": "0.24.0"
    }
  }
}

操作手順の要約

1. npm install --save-dev esbuild@0.24.0 を実行
2. package.jsonでバージョン固定（任意）
3. npm installで依存関係再構築
4. npm run devで正常起動を確認

技術的解説

エラーの本質はESモジュールのimport.metaプロパティです：

• esbuild@0.24.1が特殊な環境でこの構文解析に失敗
• Viteの設定読込(vite.config.js)時に発生
• 問題はesbuildリポジトリで#4010として追跡

降級後にエラーが解決する理由：

• esbuild@0.24.0にはバグ修正前の安定版実装が含まれる
• Vite 6.0.5+では依存関係が適切に管理されている

予防対策

1. 定期的な依存関係の更新：

   npm outdated # 古いパッケージをチェック
   npm update   # 安全な範囲で更新

2. バージョニング戦略：

   // メジャーバージョン固定で急な破壊変更を回避
   "devDependencies": {
     "vite": "~6.1.0" 
   }

3. CI環境でのビルドテスト： package-lock.jsonをコミットし、常に同一バージョンを利用

非推奨な回避策

vite@^5へのダウングレードは機能しますが、React 18やその他最新機能に制限が生じます：

npm install vite@5

長期的には最新版移行がベストプラクティスです。

結論

問題はesbuildの特定バージョンとViteの互換性の問題です。恒久的な解決には：

1. Viteを最新版に更新
2. 緊急時はesbuild@0.24.0で一時対応
3. 依存関係管理設定で再発防止

アップデート後、npm run devを再度実行すれば通常通り開発サーバーが起動します。