Vite: 「Failed to resolve import」エラーの解決方法(パスエイリアス)

Viteプロジェクトでパスエイリアスを設定し、煩雑な ../../../components のようなインポートを @/components のようなクリーンなパスに置き換えたばかりなのに、Viteが厄介なエラーを投げてきます:「Failed to resolve import」。これは、ViteとTypeScriptがモジュール解決を異なる方法で処理するために発生し、修正には2つの別々の設定を同期させる必要があります。

このガイドでは、Viteのパスエイリアスエラーを修正する2つの実証済みの方法を正確に示します:完全な制御のための手動設定、またはシンプルさのための自動化されたvite-tsconfig-pathsプラグインです。

Viteにおける「Failed to resolve import」エラー

Vite Failed to resolve importエラーは、バンドラーがカスタムパスエイリアスを使用してモジュールを見つけられない場合に表示されます。次のようなバリエーションが表示されます:

• [vite] Internal server error: Failed to resolve import "@/components/Header"
• Cannot find module '@/utils' or its corresponding type declarations
• IDEでのTypeScriptエラー TS2307

これらのエラーは開発サーバーをブロックし、ホットモジュール置換を壊し、ビルドの成功を妨げます—生産性向上のはずが障害となってしまいます。

Viteのパスエイリアスが失敗する理由を理解する

2つの設定の問題

ViteはバンドリングにRollupを使用し、TypeScriptは型チェックを別々に処理します。各ツールには独自の設定が必要です:

• Viteはモジュールバンドリングのために vite.config.ts に resolve.alias が必要
• TypeScriptは型チェックとIDEサポートのために tsconfig.json に paths が必要

これらの設定が一致しない場合、インポート解決エラーが発生します。Viteは @/components を理解できても、TypeScriptは理解できない—またはその逆です。

インポートエラーの一般的なトリガー

3つの問題がほとんどのVite resolve aliasエラーを引き起こします:

1. Node.js型の欠落: @types/node なしで path.resolve() を使用
2. 構文の不一致: Viteはオブジェクト記法を使用し、TypeScriptは配列パターンを使用
3. モジュール形式の競合: ESMプロジェクトでCommonJS固有の変数 __dirname を使用

方法1: Vite TypeScriptエイリアスの手動設定

ステップ1: vite.config.tsの設定

まず、必要なNode.js型をインストールします:

npm install -D @types/node

次に、Vite設定を更新します:

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { fileURLToPath, URL } from 'node:url'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url)),
      '@components': fileURLToPath(new URL('./src/components', import.meta.url)),
      '@utils': fileURLToPath(new URL('./src/utils', import.meta.url))
    }
  }
})

CommonJSプロジェクトの場合、__dirname で path.resolve() を使用できます:

// vite.config.ts (CommonJS)
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
      '@components': path.resolve(__dirname, './src/components'),
      '@utils': path.resolve(__dirname, './src/utils')
    }
  }
})

ステップ2: tsconfig.jsonの更新

TypeScriptが同じエイリアスを認識するように設定します:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    }
  }
}

構文の違いに注意してください:Viteは '@components' を使用し、TypeScriptは配列値を持つ "@components/*" を使用します。

セットアップの検証

インポートで設定をテストします:

// 変更前: import Button from '../../../components/Button'
import Button from '@components/Button'

IDEはオートコンプリートの提案を提供し、npm run dev はエラーなしで起動するはずです。

方法2: vite-tsconfig-pathsによる自動セットアップ

インストールと基本セットアップ

vite-tsconfig-pathsプラグインは、TypeScriptのパスをViteと自動的に同期します:

npm install -D vite-tsconfig-paths

Vite設定を更新します:

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tsconfigPaths from 'vite-tsconfig-paths'

export default defineConfig({
  plugins: [react(), tsconfigPaths()]
})

これだけです。プラグインは tsconfig.json のパスを読み取り、Viteを自動的に設定します。

手動設定に対する利点

• 単一の信頼できる情報源: tsconfig.json のみを更新
• 同期エラーなし: エイリアスは常に一致
• よりクリーンな設定ファイル: 定型コードが少ない
• モノレポサポート: 複雑なワークスペースセットアップを処理

Vite Resolve Aliasエラーのトラブルシューティング

TypeScriptなしのJavaScriptプロジェクト

JavaScriptプロジェクトの場合、代わりに jsconfig.json を作成します:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

vite-tsconfig-pathsプラグインは jsconfig.json でも動作します。

モノレポと高度なシナリオ

モノレポでは、パスがワークスペースルートに対して相対的であることを確認してください:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@app/*": ["packages/app/src/*"],
      "@shared/*": ["packages/shared/src/*"]
    }
  }
}

Windowsユーザーの場合、パス設定では常にフォワードスラッシュ(/)を使用してください—ViteとTypeScriptの両方が正しく正規化します。

ビルドと開発の不一致

開発では動作するがビルド中に失敗する場合:

1. 大文字小文字の区別の問題を確認(特にLinux/macOSで)
2. baseUrl が正しく設定されていることを確認
3. すべてのエイリアスパスがビルド出力に存在することを確認
4. ビルドツールがエイリアス設定を保持していることを確認

クイックリファレンス: 手動 vs vite-tsconfig-paths

項目	手動設定	vite-tsconfig-paths
セットアップの複雑さ	2つのファイルを維持	1つのファイルのみ
制御	完全なカスタマイズ	tsconfig.jsonに従う
メンテナンス	手動同期	自動
最適な用途	シンプルなプロジェクト、特定の要件	ほとんどのプロジェクト、モノレポ
パフォーマンス	わずかに高速(プラグインオーバーヘッドなし)	無視できる差

結論

Vite Failed to resolve importエラーの修正は、ViteとTypeScript間のモジュール解決の整合性を取ることに帰着します。手動方法は両方の設定に対する正確な制御を提供し、vite-tsconfig-pathsは同期の手間を完全に排除します。

ほとんどのプロジェクトでは、vite-tsconfig-pathsから始めてください—よりシンプルで、設定のずれを防ぎます。開発と本番環境で異なるエイリアス戦略が必要な場合、またはカスタム解決ロジックを必要とする通常とは異なるビルドセットアップで作業する場合にのみ、手動設定に切り替えてください。

よくある質問

TypeScriptがエイリアスを認識しているのに、なぜViteがインポートエラーを表示するのですか?

ViteとTypeScriptは別々の設定システムを使用します。TypeScriptは型チェックのためにtsconfig.jsonを読み取り、Viteはバンドリングのためにvite.config.tsを使用します。両方が正しく動作するには、一致するパスエイリアス設定が必要です。

TypeScriptなしのViteプロジェクトでパスエイリアスを使用できますか?

はい、パスマッピングを含むjsconfig.jsonファイルを作成し、Viteエイリアスを手動で設定するか、jsconfig.jsonとtsconfig.jsonの両方をサポートするvite-tsconfig-pathsを使用します。

Vite設定で__dirnameとimport.meta.urlを使用することの違いは何ですか?

最新のViteプロジェクトは__dirnameが利用できないESモジュールを使用します。ESM互換性のためにfileURLToPathでimport.meta.urlを使用するか、CommonJS環境でのみ__dirnameを使用してください。