logoNext.js
ドキュメントブログ学習
はじめに/ガイド/デバッグ

Next.jsでデバッグツールを使用する方法

このドキュメントでは、VS Code デバッガー、Chrome DevTools、または Firefox 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 client-side (Firefox)",
      "type": "firefox",
      "request": "launch",
      "url": "http://localhost:3000",
      "reAttach": true,
      "pathMappings": [
        {
          "url": "webpack://_N_E",
          "path": "${workspaceFolder}"
        }
      ]
    },
    {
      "name": "Next.js: debug full stack",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/next/dist/bin/next",
      "runtimeArgs": ["--inspect"],
      "skipFiles": ["<node_internals>/**"],
      "serverReadyAction": {
        "action": "debugWithEdge",
        "killOnServerStop": true,
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "webRoot": "${workspaceFolder}"
      }
    }
  ]
}

注: VS Code で Firefox のデバッグを使用するには、Firefox Debugger 拡張機能をインストールする必要があります。

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

「Next.js: debug full stack」設定では、serverReadyAction.action はサーバーの準備が整ったときに開くブラウザを指定します。debugWithEdge は Edge ブラウザを起動することを意味します。Chrome を使用している場合は、この値を debugWithChrome に変更してください。

アプリケーションの起動ポート番号を変更している場合は、http://localhost:3000 の 3000 を実際に使用しているポート番号に置き換えてください。

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

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

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

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

ブラウザ DevTools でのデバッグ

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

通常通り next dev、npm run dev、または yarn dev を実行して開発サーバーを起動します。サーバーが起動したら、任意のブラウザで http://localhost:3000（または代替 URL）を開きます。

Chrome の場合：

  • Chrome の開発者ツールを開く（Windows/Linux では Ctrl+Shift+J、macOS では ⌥+⌘+I）
  • Sources タブに移動

Firefox の場合：

  • Firefox の開発者ツールを開く（Windows/Linux では Ctrl+Shift+I、macOS では ⌥+⌘+I）
  • Debugger タブに移動

どちらのブラウザでも、クライアントサイドコードが debugger ステートメントに到達すると、コードの実行が一時停止し、そのファイルがデバッグ領域に表示されます。手動でブレークポイントを設定するためにファイルを検索することもできます：

  • Chrome：Windows/Linux では Ctrl+P、macOS では ⌘+P
  • Firefox：Windows/Linux では Ctrl+P、macOS では ⌘+P、または左パネルのファイルツリーを使用

検索時には、ソースファイルのパスは webpack://_N_E/./ で始まります。

サーバーサイドコード

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

Terminal
NODE_OPTIONS='--inspect' next dev

豆知識: NODE_OPTIONS='--inspect=0.0.0.0' を使用すると、Docker コンテナ内でアプリを実行する場合など、localhost 外からのリモートデバッグアクセスが許可されます。

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

Chrome の場合：

  1. 新しいタブを開き、chrome://inspect にアクセス
  2. Configure... をクリックして両方のデバッグポートがリストされていることを確認
  3. localhost:9229 と localhost:9230 がまだ存在しない場合は追加
  4. Remote Target セクションで Next.js アプリケーションを探す
  5. inspect をクリックして別の DevTools ウィンドウを開く
  6. Sources タブに移動

Firefox の場合：

  1. 新しいタブを開き、about:debugging にアクセス
  2. 左サイドバーの This Firefox をクリック
  3. Remote Targets で Next.js アプリケーションを探す
  4. Inspect をクリックしてデバッガーを開く
  5. Debugger タブに移動

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

ブラウザ DevTools でサーバーエラーを検査

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

Next.js は、エラーオーバーレイの Next.js バージョンインジケーターの下に Node.js アイコンを表示します。そのアイコンをクリックすると、DevTools の URL がクリップボードにコピーされます。その URL を新しいブラウザタブで開くと、Next.js サーバープロセスを検査できます。

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 デバッガーの使用方法について詳しくは、以下のドキュメントを参照してください：

カスタムサーバー

Next.jsアプリをプログラムで起動するためのカスタムサーバーの設定方法

Draft Mode

Next.jsには静的ページと動的ページを切り替えるDraft Mode機能があります。Pages Routerとの連携方法について学べます。

On this page