デバッグ

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

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

VS Code でのデバッグ

プロジェクトのルートに .vscode/launch.json ファイルを作成し、次の内容を記述します:

launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug server-side",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev"
    },
    {
      "name": "Next.js: debug client-side",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000"
    },
    {
      "name": "Next.js: debug full stack",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev",
      "serverReadyAction": {
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "action": "debugWithChrome"
      }
    }
  ]
}

Yarn を使用している場合、npm run dev は yarn dev に置き換えることができます。アプリケーションのポート番号を変更している場合は、http://localhost:3000 の 3000 を実際に使用しているポート番号に置き換えてください。

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

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

Chrome DevTools でのデバッグ

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

通常通り next dev、npm run dev、または yarn dev を実行して開発サーバーを起動します。サーバーが起動したら、Chrome で 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 フラグを渡す必要があります:

Terminal

NODE_OPTIONS='--inspect' next dev

npm run dev または yarn dev を使用している場合は、package.json の dev スクリプトを更新してください:

package.json

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

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

Terminal

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

NODE_OPTIONS='--inspect' npm run dev または NODE_OPTIONS='--inspect' yarn dev を実行しても動作しないことに注意してください。これにより、同じポートで npm/yarn プロセスと Next.js の複数のデバッガーが起動しようとします。コンソールに Starting inspector on 127.0.0.1:9229 failed: address already in use のようなエラーが表示されます。

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

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

Windows でのデバッグ

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

package.json

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

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

知っておくと便利: マシンで Windows Defender が無効になっていることを確認してください。この外部サービスは_すべてのファイル読み取り_をチェックし、next dev での Fast Refresh 時間を大幅に増加させることが報告されています。これは Next.js に関連しない既知の問題ですが、Next.js の開発に影響を与えます。

追加情報

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