Vite で path alias(@/)が効かない
Vite で path alias(@/)が効かないときは、resolve.alias と tsconfig の paths を両方設定すれば直る。
片方だけだと、型か実行時のどちらかで解決に失敗する。
公開: 更新:
npx vite build … ✗ Build failed in 15ms error during build: [vite]: Rollup failed to resolve import "@/lib/greet.js" from "/tmp/tmp.YdPI7s97L5/src/main.js". This is most likely unintended because it can break your application at runtime.
npx vite build … rendering chunks... computing gzip size... dist/main.js 0.07 kB │ gzip: 0.08 kB ✓ built in 28ms
2026-11-20 に node:20(Vite 6.4.6 / Node.js 20.20.2) で実際に打って取った出力。検証環境の詳細
要約
Vite の path alias には、Vite (resolve.alias) と TypeScript (tsconfig.paths) の 2 箇所に独立した設定が要る。
片方だけだと「ビルドは通るが型エラー」または「型は通るが実行時に解決失敗」のどちらかになる。
実行例
alias を設定していない状態では、Rollup が @/lib/greet.js を解決できずビルドが終了コード 1 で止まる。resolve.alias を足すとそのままビルドが通り、出力を実行するとエイリアス越しに読み込んだ関数が動いていることまで確認できる。
$ npx vite build
vite v6.4.6 building for production...
transforming...
✓ 1 modules transformed.
✗ Build failed in 15ms
error during build:
[vite]: Rollup failed to resolve import "@/lib/greet.js" from "/tmp/tmp.YdPI7s97L5/src/main.js".
This is most likely unintended because it can break your application at runtime.
If you do want to externalize this module explicitly add it to
`build.rollupOptions.external`
at viteLog (file:///tmp/tmp.YdPI7s97L5/node_modules/vite/dist/node/chunks/dep-Cohbwjf9.js:46698:15)
at onRollupLog (file:///tmp/tmp.YdPI7s97L5/node_modules/vite/dist/node/chunks/dep-Cohbwjf9.js:46748:5)
at onLog (file:///tmp/tmp.YdPI7s97L5/node_modules/vite/dist/node/chunks/dep-Cohbwjf9.js:46396:7)
at file:///tmp/tmp.YdPI7s97L5/node_modules/rollup/dist/es/shared/node-entry.js:22876:32
at Object.logger [as onLog] (file:///tmp/tmp.YdPI7s97L5/node_modules/rollup/dist/es/shared/node-entry.js:24873:9)
at ModuleLoader.handleInvalidResolvedId (file:///tmp/tmp.YdPI7s97L5/node_modules/rollup/dist/es/shared/node-entry.js:23615:26)
at file:///tmp/tmp.YdPI7s97L5/node_modules/rollup/dist/es/shared/node-entry.js:23573:26
$ echo $?
1$ npx vite build
vite v6.4.6 building for production...
transforming...
✓ 2 modules transformed.
rendering chunks...
computing gzip size...
dist/main.js 0.07 kB │ gzip: 0.08 kB
✓ built in 28ms
$ echo $?
0$ node dist/main.js
hello from @/lib/greet.js$ node check-alias.mjs
resolve.alias: [ { find: '@', replacement: '/tmp/tmp.YdPI7s97L5/src' } ]— 2026-11-20 時点の出力
検証環境Node.js 20.20.2 / npm 10.8.2 / Python 3.11.2 / 2026-11-20 検証(ほか 2 件)
- 検証日
- 実行環境
node:20Debian GNU/Linux 12 (bookworm)- バージョン
- Node.js 20.20.2
- npm 10.8.2
- Python 3.11.2
- Git 2.39.5
- Vite 6.4.6
この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。
解決策
1. vite.config.ts に alias を追加
// __dirname は "type": "module" の有無にかかわらず使える
import { defineConfig } from "vite";
import path from "node:path";
export default defineConfig({
resolve: {
alias: {
"@": path.resolve(__dirname, "./src"),
},
},
});// import.meta.url から組み立てても結果は同じ
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": {
"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 ドキュメント(新しいタブで開く) に載っている。
よくある原因
vite.config.tsのresolve.aliasを設定していないか、書式を誤っている。tsconfig.jsonのpathsを設定しておらず、TypeScript が解決できない。- 設定ファイルの外にある ESM コードで
__dirnameを使い、そのReferenceErrorを alias の解決失敗と混同している(vite.config.*は Vite がバンドルしてから評価するため、"type": "module"でも__dirnameは使える)。 - Vitest を併用しているが、Vitest 側の alias が抜けている。
- ESLint の
import/no-unresolvedが alias を知らない。