Nuxtで「FATAL Cannot find module ‘@nuxt/types’」エラーが出る原因

Nuxt プロジェクトを開発していると、「FATAL Cannot find module ‘@nuxt/types’」 というエラーに遭遇することがあります。これは、パッケージのバージョン不整合や型定義ファイルが削除されている場合に発生する典型的な問題です。

特に TypeScript を利用しているプロジェクトでは頻出するため、原因と解決策を整理しておくことが重要です。

目次

1. エラーが発生する背景

Nuxt は @nuxt/types という型定義パッケージを内部で利用しています。このため、以下のような状況でエラーが発生します。

  • node_modules が削除されている、または依存関係が壊れている
  • package.json に @nuxt/types が存在しない、あるいは古いバージョンを参照している
  • プロジェクトの TypeScript 設定に不整合がある

特に npm install の途中で失敗した場合や lock ファイルが壊れている場合 に発生しやすいエラーです。

2. 典型的なエラーメッセージ

FATAL Cannot find module '@nuxt/types'
Require stack:
- node_modules/@nuxt/cli/dist/cli-index.js

また、CI/CD 環境では以下のようなケースもあります。

Error: Cannot find module '@nuxt/types'
 at webpack.config.ts:2:15

これはローカルでは動作するのに、本番や CI/CD の環境でのみ失敗する場合に見られる現象です。

3. 解決方法

エラーを解消するためには、以下の対策が有効です。

  1. node_modules と lock ファイルを削除して再インストール
rm -rf node_modules package-lock.json yarn.lock
npm install
  1. @nuxt/types を明示的にインストール
npm install --save-dev @nuxt/types
  1. TypeScript 設定ファイルの確認
    tsconfig.json 内で types が正しく設定されているか確認しましょう。
{
  "compilerOptions": {
    "types": [
      "@nuxt/types"
    ]
  }
}

4. 実運用でのトラブルシューティング例（CI/CD環境）

CI/CD 環境ではローカルと異なる条件で依存関係の解決が行われるため、次のような落とし穴があります。

  • キャッシュの残骸: GitHub Actions や GitLab CI で node_modules キャッシュを有効化している場合、古い依存関係が残りエラーを引き起こす
  • lock ファイルの不整合: 開発者が異なる npm / yarn バージョンで lock ファイルを生成し、それを CI/CD が正しく解釈できない
  • 依存関係の peerDependencies 問題: Nuxt のバージョン更新で @nuxt/types の peerDependencies が変更されたが、CI/CD で反映されていない

解決策

  • CI/CD パイプラインでビルド前に必ず npm ci を実行し、lock ファイルに基づいたクリーンな環境を構築する
  • node_modules キャッシュを使う場合は、lock ファイルが変更されたときに必ずキャッシュを無効化する設定を追加する
  • ビルド環境の Node.js / npm バージョンを .nvmrc や CI/CD 設定ファイルで固定する

このように、CI/CD 環境ではキャッシュや lock ファイルの管理がカギ となります。

まとめ

「FATAL Cannot find module ‘@nuxt/types’」エラーは、依存関係の不整合や型定義の欠如によって発生します。特に CI/CD 環境ではキャッシュや lock ファイルが原因となるケースが多いため、ビルド環境をクリーンに保つことが重要です。ローカルで動作していても本番で失敗する場合は、まず依存関係の再構築を疑いましょう。

参考

タイトルとURLをコピーしました