ViteのFailed to resolve importが出たら、まずエラーにあるimport文字列と、そのimportを書いたファイルを一組で確認します。editorで補完できることと、実際に起動したViteが同じpathを解決できることは別です。cache削除や依存の全再installへ進む前に、実ファイルと有効な設定を照合します。
以下は診断用の架空例です。Viteのdev サーバーやbuild、実projectのimport試験は実行していません。利用Vite・plugin・Node.jsの版と、dev/build/SSRなどの失敗経路を記録し、その版の公式資料へ照合します。
目次
import元・import文字列・実ファイルを固定する
エラー全文からimporter、specifier、pluginや処理段階を確認します。「ファイルが見つからない」と「exportされていない」は別です。後者にaliasを追加しても原因が変わらない場合があります。
表は横にスクロールできます
| 観測 | 最初に見るもの | 直ちにしないこと |
|---|---|---|
| Failed to resolve import | import元と指定文字列 | 全依存の再install |
| 相対pathだけ失敗 | importerからの実path | project root基準で解釈 |
| aliasだけ失敗 | 有効なresolve設定 | externalへ追加して隠す |
| CIだけ失敗 | Gitで追跡済みのファイルと大小文字 | OS差だけと断定 |
| export名のエラー | 対象moduleのexport | ファイル探索の問題と混同 |
架空例のsrc/pages/Home.tsxから../components/Buttonを参照する場合、起点はそのimporterです。期待する実ファイルを紙上で解決し、実際のdirectoryと綴りが合うか確認します。生成ファイルなら、Viteが読む前に生成される契約かも調べます。
大文字小文字と共有されたファイルを確認する
Viteのtroubleshooting（新しいタブで開く）は、case-insensitive環境で開発し、case-sensitive環境でbuildすると、importの大小文字差が問題になる場合を説明しています。Button.tsxとbutton.tsxを同じと考えず、importの各path要素と実ファイルを比較します。
CIに対象ファイルが存在するかも別に見ます。ローカルにはあるが未追跡、ignore対象、生成前といった場合は、aliasが正しくても解決できません。Git管理ファイルなら、たとえば対象directoryのgit ls-files出力と照合します。ファイルを追加する場合は、そのprojectの生成物・source管理の方針に従います。
aliasのreplacementと有効なconfigを見る
ViteのShared Options（新しいタブで開く）は、ファイルシステムのパスへのaliasでは絶対pathを使うよう説明しています。相対replacementは、そのまま使われ、ファイルシステムのパスへ自動解決されるわけではありません。
表は横にスクロールできます
| 架空の確認 | 比較する内容 | 判断 |
|---|---|---|
| importは@/components/Button | @の定義があるか | 未定義ならalias経路を調査 |
| @がsrcへ向く | replacementが絶対pathか | 相対値を想定どおりと決めない |
| 複数aliasが一致 | 適用順とmatch条件 | 先の規則が別pathへ向けないか |
| 設定ファイルは正しい | 起動コマンドと読み込むconfig | 別root/configを使っていないか |
monorepoやprogrammatic APIでは、今見ているvite.configと、実際に読み込まれた設定が同じかを確認します。CLIのroot・config指定や、pluginが作るvirtual importerなども記録します。別のissueで紹介されたbuild専用の回避設定を、通常のdev経路へ無条件にコピーしません。
tsconfigのpathsはVite側の適用条件も確認する
現在の公式資料には、tsconfig pathsの解決を有効にするresolve.tsconfigPathsがあり、既定値はfalseとされています。利用版が対応するか、有効か、または既存のpath解決pluginを使うかを確認します。「TypeScriptが読めるからViteも必ず読める」「Viteは一切pathsを使えない」のどちらにも固定しません。
公式資料は、pathsが対象tsconfigのfiles/includeに一致したファイルへ適用されることや、CSS等の非JS拡張子には明示的なincludeが必要な場合も説明しています。どのファイルからimportしているかが重要です。すべてのファイル種別へ同じ解決方式が働くとみなさず、対応しない場合は相対pathやresolve.aliasなどを検討します。
表は横にスクロールできます
| editorとViteの差 | 確認する条件 | 変更前に残す記録 |
|---|---|---|
| editorだけ成功 | paths解決の有効化 | 利用Vite版と設定 |
| TSでは通りCSSで失敗 | ファイル種別とinclude | importer拡張子 |
| package内だけ失敗 | 対象tsconfigとroot | workspace・config対応 |
| plugin追加後に変化 | plugin順・独自resolve | 直前の最小差分 |
相対pathとの比較を診断に使う
検証用の変更として、同じ実ファイルへ到達する相対importとalias importを一つずつ比較すると、ファイル探索かalias経路かを絞れます。相対importが通っても、すべてのimportを一括置換して原因解決とはしません。診断用差分を戻せるようにし、有効なconfigと実ファイルの関係を直します。
存在するファイルへの内部importを、エラーを消すためだけにbuildのexternalへ追加しません。bundleから外れて実行時に解決できない問題へ移る場合があります。external化が必要なlibrary設計なら、その配布・実行契約を別に確認します。
解決後は元の経路へ戻して確認する
設定を修正したら、元のimportを使い、失敗した経路で再確認します。devで成功しただけなら、buildやSSRの成功まで報告しません。CIだけの問題なら、同じGitで追跡済みのファイルと条件で確認します。cacheの再最適化が必要な場合も、対象と理由を確認して実施します。
完了記録には、元のエラー、importer、specifier、解決先、変更した設定、確認したdev/build等の経路、未確認事項を残します。解決しなければ、最小のimporterとファイル構成、利用版、configへ範囲を絞り、特定の版やpluginの既知問題を調べます。