跳至內容
建置您的應用程式設定除錯

除錯

本文說明如何使用 VS Code 除錯器 或 Chrome 開發者工具，以完整支援原始碼對應的方式，對 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 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}"
      }
    }
  ]
}

如果您使用的是 Yarn，則可以用 yarn dev 取代 npm run dev；如果您使用的是 pnpm，則可以用 pnpm dev 取代。

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

如果您從根目錄以外的目錄執行 Next.js（例如，如果您使用 Turborepo），則需要將 cwd 新增到伺服器端和全端偵錯任務中。例如，"cwd": "${workspaceFolder}/apps/web"。

現在，前往「偵錯」面板（Windows/Linux 上為 Ctrl+Shift+D，macOS 上為 ⇧+⌘+D），選擇啟動設定，然後按 F5 或從指令面板中選擇「偵錯：開始偵錯」來開始偵錯工作階段。

在 Jetbrains WebStorm 中使用偵錯器 使用 Chrome 開發者工具進行偵錯 用戶端程式碼

透過執行 next dev、npm run dev 或 yarn dev 等指令，照常啟動您的開發伺服器。伺服器啟動後，在 Chrome 瀏覽器中開啟 https://127.0.0.1:3000（或您的替代網址）。接著，開啟 Chrome 的開發者工具（Windows/Linux 上按 Ctrl+Shift+J，macOS 上按 ⌥+⌘+I），然後前往「原始碼」分頁。

現在，每當您的用戶端程式碼執行到 debugger 陳述式時，程式碼執行就會暫停，並且該檔案會顯示在除錯區域中。您也可以按 Windows/Linux 上的 Ctrl+P 或 macOS 上的 ⌘+P 來搜尋檔案並手動設定中斷點。請注意，在此處搜尋時，您的原始碼檔案的路徑會以 webpack://_N_E/./ 開頭。

伺服器端程式碼

要使用 Chrome 開發者工具除錯伺服器端 Next.js 程式碼，您需要將 --inspect 旗標傳遞給底層的 Node.js 處理程序。

終端機
NODE_OPTIONS='--inspect' next dev

如果您使用的是 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，您應該會在「遠端目標」區塊中看到您的 Next.js 應用程式。點擊應用程式下方的「檢查」以開啟個別的開發者工具視窗，然後前往「原始碼」分頁。

在此除錯伺服器端程式碼與使用 Chrome 開發者工具除錯用戶端程式碼非常相似，不同之處在於，當您使用 Ctrl+P 或 ⌘+P 搜尋檔案時，您的原始碼檔案的路徑會以 webpack://{應用程式名稱}/./ 開頭（其中 {應用程式名稱} 將會根據您的 package.json 檔案替換為您的應用程式名稱）。

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

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

Next.js 在開發覆蓋層上會顯示一個像綠色按鈕的 Node.js 標誌。點擊該按鈕會將 Chrome DevTool 的網址複製到剪貼簿，您可以使用該網址在新分頁中開啟 Chrome DevTool 來檢查 Next.js 伺服器程序。

Copy Chrome DevTool url example

在 Windows 上除錯

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

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

無論您使用哪個平台（包括 Mac、Linux 和 Windows），cross-env 都會設定 NODE_OPTIONS 環境變數，讓您可以在不同裝置和作業系統上進行一致的除錯。

注意事項：請確保您的電腦上已停用 Windows Defender。這個外部服務會檢查*每個讀取的檔案*，據報導，這會大大增加使用 next dev 進行快速重新整理的時間。這是已知問題，與 Next.js 無關，但它確實會影響 Next.js 的開發。

更多資訊

要深入瞭解如何使用 JavaScript 除錯器，請參閱以下文件