除錯

本文件說明如何使用 VS Code 除錯器、Chrome 開發人員工具或 Firefox 開發人員工具，針對您的 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://127.0.0.1:3000"
    },
    {
      "name": "Next.js: debug client-side (Firefox)",
      "type": "firefox",
      "request": "launch",
      "url": "https://127.0.0.1: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 除錯器擴充功能。

如果您使用 Yarn，npm run dev 可以替換為 yarn dev；如果您使用 pnpm，則可以替換為 pnpm dev。

在「Next.js: debug full stack」設定中，serverReadyAction.action 指定伺服器就緒時要開啟的瀏覽器。debugWithEdge 表示啟動 Edge 瀏覽器。如果您使用 Chrome，請將此值變更為 debugWithChrome。

如果您要變更應用程式啟動的連接埠號碼，請將 https://127.0.0.1:3000 中的 3000 替換為您正在使用的連接埠。

如果您是從根目錄以外的目錄執行 Next.js (例如，如果您正在使用 Turborepo)，則需要在伺服器端和完整堆疊除錯任務中新增 cwd。例如，"cwd": "${workspaceFolder}/apps/web"。

現在前往「除錯」面板 (Windows/Linux 上為 Ctrl+Shift+D，macOS 上為 ⇧+⌘+D)，選取啟動設定，然後按下 F5 或從命令面板中選取「除錯：開始除錯」以開始您的除錯工作階段。

按一下列出執行階段設定的下拉式選單，然後按一下 Edit Configurations... (編輯設定...)。建立一個 JavaScript Debug 除錯設定，並以 https://127.0.0.1:3000 作為 URL。依您的喜好自訂 (例如，用於除錯的瀏覽器、儲存為專案檔案)，然後按一下 OK (確定)。執行此除錯設定，選取的瀏覽器應會自動開啟。此時，您應該會有 2 個處於除錯模式的應用程式：NextJS 節點應用程式和用戶端/瀏覽器應用程式。

使用瀏覽器開發人員工具進行除錯

用戶端程式碼

如常執行 next dev、npm run dev 或 yarn dev 來啟動您的開發伺服器。伺服器啟動後，在您偏好的瀏覽器中開啟 https://127.0.0.1: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/./ 開頭。

伺服器端程式碼

若要使用瀏覽器開發人員工具除錯伺服器端 Next.js 程式碼，您需要將 --inspect 旗標傳遞至底層 Node.js 處理程序

終端機

NODE_OPTIONS='--inspect' next dev

小訣竅：使用 NODE_OPTIONS='--inspect=0.0.0.0' 以允許在 localhost 外部進行遠端除錯存取，例如在 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://node.dev.org.tw/en/docs/inspector
ready - started server on 0.0.0.0:3000, url: https://127.0.0.1:3000

針對 Chrome

開啟新分頁並瀏覽 chrome://inspect
按一下 Configure... (設定...) 以確保列出兩個除錯連接埠
新增 localhost:9229 和 localhost:9230 (如果它們尚未存在)
在 Remote Target (遠端目標) 區段中尋找您的 Next.js 應用程式
按一下 inspect (檢查) 以開啟個別的開發人員工具視窗
前往 Sources (來源) 標籤

針對 Firefox

開啟新分頁並瀏覽 about:debugging
按一下左側邊欄中的 This Firefox (此 Firefox)
在 Remote Targets (遠端目標) 下方，尋找您的 Next.js 應用程式
按一下 Inspect (檢查) 以開啟除錯器
前往 Debugger (除錯器) 標籤

伺服器端程式碼除錯與用戶端除錯類似。當搜尋檔案 (Ctrl+P/⌘+P) 時，您的原始碼檔案的路徑將以 webpack://{application-name}/./ 開頭 (其中 {application-name} 將會根據您的 package.json 檔案替換為您的應用程式名稱)。

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

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

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 將會設定 NODE_OPTIONS 環境變數，無論您使用的是哪個平台 (包括 Mac、Linux 和 Windows)，並讓您在不同裝置和作業系統之間保持一致地進行除錯。

小訣竅：請確保在您的電腦上停用 Windows Defender。此外部服務將會檢查每個讀取的檔案，據報告指出，這會大幅增加 next dev 的快速重新整理時間。這是已知問題，與 Next.js 無關，但確實會影響 Next.js 開發。

除錯