デバッグ

このドキュメントでは、VS CodeデバッガーまたはChrome DevToolsを使用して、フルソースマップサポート付きでNext.jsのフロントエンドおよびバックエンドコードをデバッグする方法を説明します。

Node.jsに接続できる任意のデバッガーを使用して、Next.jsアプリケーションをデバッグできます。詳細については、Node.jsのデバッグガイドを参照してください。

VS Codeでのデバッグ

プロジェクトのルートに、以下の内容の.vscode/launch.jsonファイルを作成します：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: サーバーサイドをデバッグ",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev"
    },
    {
      "name": "Next.js: クライアントサイドをデバッグ",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000"
    },
    {
      "name": "Next.js: フルスタックをデバッグ",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/.bin/next",
      "runtimeArgs": ["--inspect"],
      "skipFiles": ["<node_internals>/**"],
      "serverReadyAction": {
        "action": "debugWithEdge",
        "killOnServerStop": true,
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "webRoot": "${workspaceFolder}"
      }
    }
  ]
}

Yarnを使用している場合はnpm run devをyarn devに、pnpmを使用している場合はpnpm devに置き換えることができます。

ポート番号を変更している場合は、http://localhost:3000の3000を使用しているポート番号に置き換えてください。

ルート以外のディレクトリからNext.jsを実行している場合（例：Turborepoを使用している場合）、サーバーサイドとフルスタックのデバッグタスクにcwdを追加する必要があります。例："cwd": "${workspaceFolder}/apps/web"。

次に、デバッグパネル（Windows/Linuxの場合はCtrl+Shift+D、macOSの場合は⇧+⌘+D）に移動し、起動構成を選択して、F5を押すか、コマンドパレットからデバッグ：デバッグを開始を選択してデバッグセッションを開始します。

JetBrains WebStormでのデバッガーの使用

ランタイム構成のドロップダウンメニューをクリックし、Edit Configurations...をクリックします。URLにhttp://localhost:3000を指定してJavaScript Debugデバッグ構成を作成します。好みにカスタマイズし（デバッグ用のブラウザなど）、OKをクリックします。このデバッグ構成を実行すると、選択したブラウザが自動的に開きます。この時点で、NextJSノードアプリケーションとクライアント/ブラウザアプリケーションの2つのアプリケーションがデバッグモードになっているはずです。

Chrome DevToolsでのデバッグ

クライアントサイドコード

通常通り、next dev、npm run dev、またはyarn devを実行して開発サーバーを起動します。サーバーが起動したら、ChromeでURLを開きます（http://localhost:3000またはその他のURL）。次に、Chrome開発者ツール（Windows/Linuxの場合はCtrl+Shift+J、macOSの場合は⌥+⌘+I）を開き、Sourcesタブに移動します。

クライアントサイドコードがdebuggerステートメントに到達すると、コード実行が一時停止し、そのファイルがデバッグエリアに表示されます。Windows/Linuxの場合はCtrl+P、macOSの場合は⌘+Pを押してファイルを検索し、手動でブレークポイントを設定することもできます。ここで検索する際、ソースファイルのパスはwebpack://_N_E/./から始まることに注意してください。

サーバーサイドコード

Chrome DevToolsでサーバーサイドNext.jsコードをデバッグするには、基盤となるNode.jsプロセスに--inspectフラグを渡す必要があります：

NODE_OPTIONS='--inspect' next dev

npm run devまたはyarn devを使用している場合は、package.jsonのdevスクリプトを更新する必要があります：

{
  "scripts": {
    "dev": "NODE_OPTIONS='--inspect' next dev"
  }
}

--inspectフラグを付けてNext.jsの開発サーバーを起動すると、次のように表示されます：

Debugger listening on ws://127.0.0.1:9229/0cf90313-350d-4466-a748-cd60f4e47c95
For help, see: https://nodejs.org/en/docs/inspector
ready - started server on 0.0.0.0:3000, url: http://localhost:3000

サーバーが起動したら、Chromeで新しいタブを開き、chrome://inspectにアクセスします。Remote TargetセクションにNext.jsアプリケーションが表示されるはずです。アプリケーションの下のinspectをクリックして、別のDevToolsウィンドウを開き、Sourcesタブに移動します。

ここでのサーバーサイドコードのデバッグは、Chrome DevToolsでクライアントサイドコードをデバッグするのとほぼ同じですが、Ctrl+Pまたは⌘+Pでファイルを検索する際、ソースファイルのパスはwebpack://{アプリケーション名}/./から始まります（{アプリケーション名}はpackage.jsonファイルに従ってアプリケーションの名前に置き換えられます）。

Chrome DevToolsでサーバーエラーを検査

エラーが発生した場合、ソースコードを検査することでエラーの根本原因を追跡するのに役立ちます。

Next.jsは、緑のボタンのようなNode.jsロゴを開発オーバーレイに表示します。そのボタンをクリックすると、Chrome DevToolのURLがクリップボードにコピーされ、そのURLで新しいブラウザタブを開いてChrome DevToolでNext.jsサーバープロセスを検査できます。

Windowsでのデバッグ

Windowsユーザーは、NODE_OPTIONS='--inspect'の構文がWindowsプラットフォームでサポートされていないため、問題に遭遇する可能性があります。これを回避するには、開発依存関係としてcross-envパッケージをインストール（npmとyarnで-D）し、devスクリプトを次のように置き換えます。

{
  "scripts": {
    "dev": "cross-env NODE_OPTIONS='--inspect' next dev"
  }
}

cross-envは、使用しているプラットフォーム（Mac、Linux、Windows）に関係なくNODE_OPTIONS環境変数を設定し、デバイスや異なるオペレーティングシステム間で一貫したデバッグを可能にします。

補足: Windows Defenderをマシンで無効にしてください。この外部サービスは、読み取られる_すべてのファイル_をチェックするため、next devでの高速更新時間を大幅に増加させることが報告されています。これは Next.js に関連する既知の問題ではありませんが、Next.js の開発に影響を与えます。

詳細情報

JavaScriptデバッガーの使用方法の詳細については、以下のドキュメントを参照してください：

• VS CodeでのNode.jsデバッグ：ブレークポイント
• Chrome DevTools：JavaScriptのデバッグ