NextJS入門：トラブルシューティング：よくある問題と解決方法

NextJS を開発していると様々なトラブルが発生します。

この記事ではよく発生するトラブルの原因と解決方法を解説します。

Contents

問題1: ポート3000が既に使用されている
問題2: Node.jsのバージョンが古い
問題3: キャッシュの問題
問題4: モジュールが見つからないエラー
問題5: ビルドは成功するが本番環境でエラー
問題6: CSS/スタイルが適用されない
問題7: TypeScriptの型エラー
問題8: Hot Reloadが動作しない
主なトラブルカテゴリ
まとめ：NextJS入門のトラブルシューティング

問題1: ポート3000が既に使用されている

発生する状況:

他のアプリケーション（React、Vue、Express等）が既にポート3000で動いている
前回のNext.jsプロセスが正常に終了せずにポートを占有している
複数のNext.jsプロジェクトを同時に起動しようとしている

エラーメッセージ例:

Bash

Error: listen EADDRINUSE: address already in use :::3000

解決方法:

Bash

# 別のポートで起動（推奨）
npm run dev -- -p 3001

# または使用中のプロセスを確認・停止
# Mac/Linux
lsof -ti:3000 | xargs kill -9

# Windows (PowerShell)
Get-Process -Id (Get-NetTCPConnection -LocalPort 3000).OwningProcess | Stop-Process

問題2: Node.jsのバージョンが古い

発生する状況:

システムに古いNode.jsがインストールされている（v16以下など）
新しいNext.jsの機能を使おうとしている
プロジェクト作成時にバージョンエラーが発生

エラーメッセージ例:

Bash

You are using Node.js 16.14.0. For Next.js, Node.js version >= 18.17.0 is required.

解決方法:

bash

Bash

# Node.jsのバージョン確認
node --version

# nvm（Node Version Manager）を使用してアップデート
# インストール後
nvm install --lts
nvm use --lts

# n（Node.js version management）を使用
npm install -g n
n latest

# 公式サイトから直接インストールも可能

問題3: キャッシュの問題

発生する状況:

依存関係を変更した後に古いコードが動作している
ビルドエラーが解決されない
新しく追加したパッケージが認識されない
開発サーバーで変更が反映されない

症状例:

削除したコンポーネントがまだ表示される
新しいライブラリをインストールしたのに「モジュールが見つからない」エラー
ビルドは通るのにランタイムエラーが発生する

解決方法:

Bash

# Next.jsのキャッシュをクリア
rm -rf .next
npm run dev

# node_modulesも含めて完全リセット（強力）
rm -rf .next node_modules package-lock.json
npm install
npm run dev

# Windows（PowerShell）の場合
Remove-Item -Recurse -Force .next
Remove-Item -Recurse -Force node_modules
Remove-Item package-lock.json
npm install

問題4: モジュールが見つからないエラー

発生する状況:

パッケージをインストールしたのに認識されない
TypeScript型定義ファイルが見つからない
相対パスでのインポートが間違っている

エラーメッセージ例:

Bash

Module not found: Can't resolve 'lodash'
Cannot find module 'lodash' or its corresponding type declarations

解決方法:

Bash

# パッケージの再インストール
npm install lodash

# TypeScript用の型定義も必要な場合
npm install --save-dev @types/lodash

# インポートパスを確認
import _ from 'lodash'  // 正しい
import _ from './lodash'  // 間違い

問題5: ビルドは成功するが本番環境でエラー

発生する状況:

開発環境では動作するが、npm run build 後の npm run start でエラー
環境変数の設定が間違っている
動的インポートの問題

エラーメッセージ例:

Bash

ReferenceError: window is not defined
Error: process is not defined

解決方法:

TypeScript

// ブラウザ専用のコードはuseEffectで実行
import { useEffect, useState } from 'react'

export default function Component() {
  const [mounted, setMounted] = useState(false)

  useEffect(() => {
    setMounted(true)
    // ブラウザ専用のコードをここに記述
    console.log(window.location.href)
  }, [])

  if (!mounted) return null

  return <div>コンテンツ</div>
}

問題6: CSS/スタイルが適用されない

発生する状況:

Tailwind CSSの設定が正しくない
CSS Modulesのクラス名が正しく読み込まれない
グローバルCSSが他のページで適用されない

解決方法:

typescript

TypeScript

// CSS Modulesの正しい使用法
import styles from './Component.module.css'

export default function Component() {
  return <div className={styles.container}>コンテンツ</div>
}

css

CSS

/* Component.module.css */
.container {
  background-color: blue;
}

問題7: TypeScriptの型エラー

発生する状況:

Next.js特有の型定義が認識されない
カスタムコンポーネントの型が正しく推論されない

解決方法:

Bash

# TypeScript設定を再確認
npx tsc --noEmit

# Next.jsの型定義を再生成
rm -rf .next
npm run dev

問題8: Hot Reloadが動作しない

発生する状況:

ファイルを変更してもブラウザが自動更新されない
WSL2（Windows Subsystem for Linux）環境での使用
Docker環境での開発

解決方法:

JavaScript

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  // WSL2環境での設定
  webpack: (config) => {
    config.watchOptions = {
      poll: 1000,
      aggregateTimeout: 300,
    }
    return config
  },
}

module.exports = nextConfig

主なトラブルカテゴリ

環境・設定関連のトラブルでは、ポート3000の競合問題は別ポートでの起動や既存プロセスの停止で対応でき、Node.jsバージョンの古さはnvmやn等のバージョン管理ツールでの更新により解決します。

キャッシュ・依存関係の問題は、.nextフォルダの削除やnode_modulesの再インストールによって解決することが多く、モジュールが見つからないエラーはパッケージの再インストールや正しいインポートパスの確認が必要です。

実行時エラーとして、開発環境では動作するが本番環境でエラーが発生する場合は、ブラウザ専用のコードをuseEffectで適切に管理し、サーバーサイドレンダリングとの互換性を保つことが重要です。

スタイリングの問題では、CSS ModulesやTailwind CSSの設定確認、正しいクラス名の使用方法の見直しが有効です。TypeScriptの型エラーは型定義の再生成やtsconfig.jsonの設定確認で対処し、Hot Reloadの不具合はWebpackの設定調整、特にWSL2やDocker環境ではpolling設定が効果的です。