コンテンツにスキップ
アプリケーションの構築設定デバッグ

デバッグ

このドキュメントでは、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": "https://:3000"
    },
    {
      "name": "Next.js: debug client-side (Firefox)",
      "type": "firefox",
      "request": "launch",
      "url": "https://:3000",
      "reAttach": true,
      "pathMappings": [
        {
          "url": "webpack://_N_E",
          "path": "${workspaceFolder}"
        }
      ]
    },
    {
      "name": "Next.js: debug full stack",
      "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}"
      }
    }
  ]
}

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

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

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

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

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

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

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

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

ブラウザのDevToolsでのデバッグ

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

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

Chromeの場合

  • ChromeのDeveloper Toolsを開きます（Windows/LinuxではCtrl+Shift+J、macOSでは⌥+⌘+I）
  • Sourcesタブに移動します

Firefoxの場合

  • FirefoxのDeveloper Toolsを開きます（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フラグを渡す必要があります

ターミナル
NODE_OPTIONS='--inspect' next dev

ヒント: Dockerコンテナでアプリを実行している場合など、localhost外からのリモートデバッグアクセスを許可するには、NODE_OPTIONS='--inspect=0.0.0.0'を使用します。

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

package.json
{
  "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://node.dokyumento.jp/en/docs/inspector
ready - started server on 0.0.0.0:3000, url: https://: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のバージョンインジケーターの下に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デバッガーの使用方法の詳細については、以下のドキュメントを参照してください