Vite で path alias（@/）が解決できない

要約

Vite の path alias は Vite (resolve.alias) と TypeScript (tsconfig.paths) の 2 箇所に独立した設定が必要。
片方だけだと「ビルドは通るが型エラー」または「型は通るが実行時に解決失敗」のどちらかになる。

よくある原因

1. vite.config.ts の resolve.alias 未設定、または書式ミス。
2. tsconfig.json の paths 未設定で TypeScript が解決できない。
3. ESM 環境で __dirname が無く path.resolve(__dirname, ...) が ReferenceError。
4. Vitest を併用しているが Vitest 側の alias が抜けている。
5. ESLint の import/no-unresolved が alias を知らない。

解決策

1. vite.config.ts に alias を追加（CJS / ESM）

// CJS（package.json に "type": "module" が無い場合）
import { defineConfig } from "vite";
import path from "node:path";
 
export default defineConfig({
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
});

// ESM（"type": "module" がある場合）
import { defineConfig } from "vite";
import { fileURLToPath, URL } from "node:url";
 
export default defineConfig({
  resolve: {
    alias: {
      "@": fileURLToPath(new URL("./src", import.meta.url)),
    },
  },
});

2. tsconfig.json に paths を追加

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

設定後は VS Code の TypeScript Server を再起動する（Cmd+Shift+P → TypeScript: Restart TS Server）。

3. Vitest を使うなら同じ alias を vitest.config.ts に書く

mergeConfig で vite.config.ts を取り込めば二重管理を避けられる。

4. ESLint の resolver を入れる

npm install -D eslint-import-resolver-typescript

.eslintrc に settings: { 'import/resolver': { typescript: true } } を追加する。
詳細は Vite の Shared Options ドキュメント を参照。