エラーのシナリオReactコンポーネントの構築に集中しているとき、ファイルを保存してホットリロードを期待したのに、画面が赤くなってしまったことはありませんか。次のような巨大なエラーオーバーレイが表示されます。
Module not found: Can't resolve './Component' in '/src/components'
ほとんどすべてのReact開発者が、いつかはこの壁にぶつかります。これは単純に、Vite、Webpack、Turbopackなどのバンドラーが、指定された場所にファイルを見つけられないことを意味しています。サイドバーにファイルが存在しているのが見えていても、コンパイラは完全に見失っている状態です。
なぜこれが起こるのかコンパイラがパスの解決に失敗する主な理由は、通常次の5つのいずれかです。
- 単純なタイポ（入力ミス）:
import Header from './Headr'と書いてしまった。誰にでもあることです。- 大文字・小文字の区別: ファイル名をNavbar.jsxとしたのに、navbarとしてインポートした。これはWindowsでは動作しますが、VercelやNetlifyのようなLinuxベースのデプロイ用サーバーでは即座にエラーになります。- 拡張子の混乱: Viteは、以前のバージョンのCreate React Appとは異なり、インポートパスに明示的な.jsxや.tsx拡張子を必要とすることがよくあります。- パスの深さ: 実際には3レベル深い場所にあり../../../が必要なのに、../を使っている。- 古いキャッシュ: ビルドツールが、すでに存在しない古いファイル構造を記憶している。## ステップバイステップの修正方法### 1. 相対パスを監査するまずは実際のパスを確認することから始めましょう。エラーメッセージをよく見てください。どのディレクトリを検索しているかが正確に示されています。インポートが記述されているファイルから、手動でパスを辿ってみてください。90%の場合、ファイルは思っているよりも1つ上、あるいは下のフォルダにあります。 誤り:
// 場所: src/components/layout/Header.js
import Button from './components/Button'; // エラー: 'components' は 'layout' の子ではなく、兄弟ディレクトリです。
正しい例:
// まず '../' を使って1つ上の階層に移動します
import Button from '../Button';
2. 大文字・小文字の罠を解決するこれはウェブ開発において最も厄介なバグの一つです。WindowsやmacOSは一般的に大文字・小文字を区別しません。つまり、UserCard.js と usercard.js を同じファイルとして扱います。しかし、Linuxはこれらを区別します。インポート時の記述がファイル名と正確に一致していない場合、ローカルでは動作してもデプロイ時にクラッシュします。
ファイル名を変更したのにGitがそれを認識しない場合は、次のコマンドを使用して強制的に変更を適用してください。
git mv src/components/oldname.js src/components/OldName.js
3. ViteとNext.jsの拡張子を処理するViteのような最新のビルドツールは、以前のWebpackのデフォルト設定よりも厳格です。コンポーネントをインポートして解決エラーが発生する場合は、拡張子を明示的に追加してみてください。
import MyComponent from './MyComponent.jsx';
拡張子を追加して問題が解決した場合は、そのまま明示的に記述し続ける（Viteでは推奨されます）か、vite.config.js を更新して resolve オブジェクトの extensions に ['.js', '.jsx', '.ts', '.tsx'] を含めるようにします。
4. 絶対パスインポートに切り替える「ドット・ドット・スラッシュ（../）」地獄と戦うのはもうやめましょう。絶対パスインポートを使用すると、src フォルダをルートとして参照できるため、コードがより綺麗になり、ファイルの移動も容易になります。これはパスの問題に対する恒久的な解決策です。
プロジェクトのルートに jsconfig.json（TypeScriptの場合は tsconfig.json）を追加します。
{
"compilerOptions": {
"baseUrl": "src"
}
}
これで、ファイルの深さに関係なく、次のようにコンポーネントをインポートできるようになります。
import Button from 'components/shared/Button';
5. キャッシュを削除する大規模なリファクタリングやブランチの切り替え後に、開発サーバーが混乱することがあります。コードが完璧なのにエラーが消えない場合は、内部キャッシュをクリアしてください。ターミナルを停止して、以下を実行します。
- Vite:
rm -rf node_modules/.vite && npm run dev- Next.js:rm -rf .next && npm run dev- CRA: 単純にnpm startでプロセスを再起動します。## 修正を確認する方法ホットリロードを過信しないでください。エラーが完全に解消されたことを確認するために、次の3つのステップを実行しましょう。 - ハードリフレッシュ: ブラウザで
Shiftキーを押しながら更新ボタンをクリックし、フロントエンドのキャッシュをクリアします。- ターミナルの確認: 隠れた警告なしに "Compiled successfully" メッセージが表示されていることを確認します。- プロダクションビルドの実行: ローカルでnpm run buildを実行します。ビルドに成功すれば、パスの解決は確実であり、デプロイ時に壊れることはありません。## 解決策のまとめ原因クイックフィックスタイポimport名をファイル名と正確に一致させる。パスの階層../の階層を慎重に数える。OSによる大文字・小文字git mvを使用して、Linux向けにファイル名の大文字・小文字を修正する。Viteの設定インポートに.jsx拡張子を追加する。ゴーストエラー.viteまたは.nextフォルダを削除して再起動する。