如何在 Next.js 中使用除錯工具

本文件解釋瞭如何使用 VS Code 偵錯程式、Chrome 開發者工具 或 Firefox 開發者工具 除錯您的 Next.js 前端和後端程式碼，並支援完整的源對映。

任何可以附加到 Node.js 的偵錯程式也可以用於除錯 Next.js 應用程式。您可以在 Node.js 除錯指南中找到更多詳細資訊。

使用 VS Code 除錯

在專案根目錄下建立一個名為 .vscode/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/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 擴充套件。

如果您使用的是 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...。建立一個 JavaScript Debug 除錯配置，並將 https://:3000 作為 URL。根據您的喜好進行自定義（例如，用於除錯的瀏覽器，儲存為專案檔案），然後點選 OK。執行此除錯配置，所選瀏覽器應自動開啟。此時，您應該有兩個應用程式處於除錯模式：NextJS node 應用程式和客戶端/瀏覽器應用程式。

使用瀏覽器開發者工具除錯

客戶端程式碼

透過執行 next dev、npm run dev 或 yarn dev 啟動您的開發伺服器。伺服器啟動後，在您喜歡的瀏覽器中開啟 https://: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/./ 開頭。

React 開發者工具

對於 React 特定的除錯，請安裝 React 開發者工具 瀏覽器擴充套件。這個基本工具可以幫助您：

• 檢查 React 元件
• 編輯 props 和 state
• 識別效能問題

伺服器端程式碼

要使用瀏覽器開發者工具除錯伺服器端 Next.js 程式碼，您需要向底層 Node.js 程序傳遞 --inspect 標誌。

NODE_OPTIONS='--inspect' next dev

溫馨提示：使用 NODE_OPTIONS='--inspect=0.0.0.0' 可以允許在 localhost 之外進行遠端除錯訪問，例如在 Docker 容器中執行應用程式時。

如果您正在使用 npm run dev 或 yarn dev，那麼您應該更新 package.json 中的 dev 指令碼。

{
  "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.com.tw/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 開啟一個獨立的開發者工具視窗
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 檔案替換為您的應用程式名稱）。

使用瀏覽器開發者工具檢查伺服器錯誤

當您遇到錯誤時，檢查原始碼可以幫助追蹤錯誤的根本原因。

Next.js 將在錯誤疊加層上的 Next.js 版本指示器下方顯示一個 Node.js 圖示。點選該圖示，開發者工具 URL 將複製到剪貼簿。您可以開啟一個新瀏覽器標籤頁，使用該 URL 來檢查 Next.js 伺服器程序。

在 Windows 上除錯

Windows 使用者在使用 NODE_OPTIONS='--inspect' 時可能會遇到問題，因為 Windows 平臺不支援該語法。為了解決這個問題，請將 cross-env 包作為開發依賴項安裝（使用 npm 和 yarn 時為 -D），並將 dev 指令碼替換為以下內容。

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

cross-env 將設定 NODE_OPTIONS 環境變數，無論您在哪個平臺（包括 Mac、Linux 和 Windows），並允許您在不同裝置和作業系統之間進行一致的除錯。

溫馨提示：確保您的機器上停用了 Windows Defender。此外部服務將檢查每個讀取的檔案，據報道這會大大增加 next dev 的快速重新整理時間。這是一個已知問題，與 Next.js 無關，但確實會影響 Next.js 開發。

更多資訊

要了解更多關於如何使用 JavaScript 偵錯程式，請參閱以下文件：

• VS Code 中的 Node.js 除錯：斷點
• Chrome 開發者工具：除錯 JavaScript
• Firefox 開發者工具：偵錯程式