デバッグ

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

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

VS Codeでデバッグする

プロジェクトの root に .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 拡張機能をインストールする必要があります。

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

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

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

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

Jetbrains WebStorm でデバッガーを使用する

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

ブラウザ 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 フラグを渡す必要があります:

ターミナル

NODE_OPTIONS='--inspect' next dev

Good to know: ローカルホスト以外でリモートデバッグアクセスを許可するには、NODE_OPTIONS='--inspect=0.0.0.0' を使用します。これは、アプリを Docker コンテナで実行しているときなどに役立ちます。

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://nodejs.org/en/docs/inspector
ready - started server on 0.0.0.0:3000, url: http://localhost:3000

Chromeの場合:

1. 新しいタブを開き、chrome://inspect を訪問します
2. Remote Target セクションで Next.js アプリケーションを探します
3. inspect をクリックして、別の DevTools ウィンドウを開きます
4. 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 パッケージを開発依存関係としてインストールし（-D は npm および yarn で使用）、次の内容で dev スクリプトを置き換えます。

package.json

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

cross-env を使用することで、どのプラットフォーム（Mac、Linux、Windows を含む）であっても NODE_OPTIONS 環境変数が設定され、デバイスやオペレーティングシステムに関係なく、一貫してデバッグを行うことができます。

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

詳細情報

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

• Node.js debugging in VS Code: Breakpoints
• Chrome DevTools: Debug JavaScript
• Firefox DevTools: Debugger