Sponsor
ChatHubChatHub — Use GPT-4, Gemini, Claude 3.5 and more chatbots side-by-side
ここをクリック
Menu

デバッグ

このドキュメントでは、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/.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に変更してください。

アプリケーションの起動ポート番号を変更している場合は、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をクリックします。このデバッグ設定を実行すると、選択したブラウザが自動的に開きます。この時点で、デバッグモードで2つのアプリケーションが実行されているはずです：NextJSのノードアプリケーションとクライアント/ブラウザアプリケーションです。

ブラウザDevToolsでのデバッグ

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

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

Terminal
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の開発サーバーを起動すると、次のように表示されます：

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