Vite / Vitestでtsconfigのpathsエイリアスが認識されない時の対処法

Vite Vitest TypeScript Frontend
結論

npm i -D vite-tsconfig-paths を導入し vite.config.ts に tsconfigPaths() を追加すると自動解決されます。

// Vitest公式推奨：vitest.config.ts でのプログレッシブ設定
import { defineConfig } from 'vitest/config';
import tsconfigPaths from 'vite-tsconfig-paths';

export default defineConfig({
  plugins: [tsconfigPaths()],
  test: {
    globals: true,
    environment: 'jsdom',
  },
});

発生原因：TypeScriptとViteバンドラの解釈分離

Vitest公式ドキュメントの記述の通り、tsconfig.json の paths は TypeScript の型チェッカー（tsc）がエディタ上で補完・型判定を行うための設定です。 ViteおよびVitestの実行エンジン（esbuild / Rollup）はデフォルトで tsconfig.json をパースしないため、型エラーにならなくても実行時に Cannot find module '@/...' が発生します。

トラブル事例と失敗パターン

1. defineConfig のインポート元の間違い

Vitestの設定ファイル（vitest.config.ts）を作成する際、vite から defineConfig をインポートしてしまうと、test プロパティが無視されたり型エラーを起こします。

// ❌ 誤り：vite からインポートすると test 設定が無視される
import { defineConfig } from 'vite';

// ⭕ 正解：vitest/config からインポートする
import { defineConfig } from 'vitest/config';

2. baseUrl の欠落

tsconfig.json 内で paths のみを設定し baseUrl: "." を書き忘れていると、vite-tsconfig-paths プラグインがパスの基準位置を特定できず失敗します。

正しい設定手順

  1. パッケージマネージャで vite-tsconfig-paths を開発依存関係としてインストールする
  2. tsconfig.json 内に "baseUrl": "." が指定されているか確認する
  3. vitest.config.ts (または vite.config.ts) に tsconfigPaths() を登録する
// tsconfig.json の必須指定
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}