Next.jsでローカルではビルド成功するのに、Vercelで"Type error: Cannot find module"が発生

tl;dr

• Next.jsのアプリケーションをVercel上に自動デプロイする際に、ローカルでのnpm run buildは成功するのに、Vercel上でのビルドにて、コンポーネントをimportする箇所で以下のビルドエラーが発生

Type error: Cannot find module '@/components/{コンポーネント}' or its corresponding type declarations.

• 以下が原因の可能性が高い。詳細は後述
  1. importパスの大文字小文字が誤っている
  2. 過去にファイル名を修正したキャッシュが残っている

対処方法

1. importパスの大文字小文字が誤っている

概要

• Vercel公式ドキュメントでも案内されているケース¹
• Vercelのファイルシステムは大文字小文字を区別する
• ローカル環境で大文字小文字を区別しないファイルシステムや設定が使われている場合に、パスに誤りがあってもビルドを通してしまう

対応

• エラー発生箇所のimport のパスを見直す
• ローカルでも以下コマンドで大文字小文字を区別するよう設定し、ビルドしなおす

  git config core.ignorecase false
  

2. 過去にファイル名を修正したキャッシュが残っている

概要

• ファイル名を修正した際にキャッシュが残っており、ローカルでのみビルドが通る
• 筆者はこちらに該当し、解決に時間がかかりました²

対応

• gitでキャッシュクリアし、差分をコミット、プッシュする

  • git add --allを実行した時点でエラーが発生していたファイルの差分が出ていればこちらが該当

    git rm -r --cached .
    git add --all .
    git commit -a -m "Versioning untracked files"
    git push
    

参考

1. How do I resolve a 'module not found' error? ↩

2. Vercel Cannot find module or its corresponding type declarations during "npm run build" [duplicate] ↩