除錯

本文件說明如何透過支援完整原始碼對應 (source maps) 的方式，使用 VS Code 除錯器 或 Chrome DevTools 來對 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": "http://localhost:3000"
    },
    {
      "name": "Next.js: debug full stack",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev",
      "serverReadyAction": {
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "action": "debugWithChrome"
      }
    }
  ]
}

若您使用 Yarn，可將 npm run dev 替換為 yarn dev。如果您 變更了應用程式的啟動埠號，請將 http://localhost:3000 中的 3000 替換為您實際使用的埠號。

接著前往除錯面板（Windows/Linux 使用 Ctrl+Shift+D，macOS 使用 ⇧+⌘+D），選擇一個啟動配置，然後按下 F5 或從命令選擇器中選擇 Debug: Start Debugging 來開始除錯工作階段。

在 Jetbrains WebStorm 中使用除錯器

點擊執行時配置的下拉選單，選擇 Edit Configurations...。建立一個 Javascript Debug 除錯配置，將 http://localhost:3000 設為 URL。根據您的喜好進行自訂（例如選擇除錯用的瀏覽器、儲存為專案檔案等），然後點擊 OK。執行此除錯配置後，所選的瀏覽器應會自動開啟。此時，您應該會有兩個應用程式處於除錯模式：NextJS 節點應用程式和客戶端/瀏覽器應用程式。

使用 Chrome DevTools 進行除錯

客戶端程式碼

像平常一樣執行 next dev、npm run dev 或 yarn dev 來啟動開發伺服器。伺服器啟動後，在 Chrome 中開啟 http://localhost:3000（或您的替代 URL）。接著開啟 Chrome 的開發者工具（Windows/Linux 使用 Ctrl+Shift+J，macOS 使用 ⌥+⌘+I），然後前往 Sources 分頁。

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

伺服器端程式碼

要使用 Chrome DevTools 除錯伺服器端的 Next.js 程式碼，您需要將 --inspect 標記傳遞給底層的 Node.js 程序：

NODE_OPTIONS='--inspect' next dev

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

請注意，執行 NODE_OPTIONS='--inspect' npm run dev 或 NODE_OPTIONS='--inspect' yarn dev 是無效的。這會嘗試在同一個埠上啟動多個除錯器：一個用於 npm/yarn 程序，另一個用於 Next.js。您將在控制台中看到類似 Starting inspector on 127.0.0.1:9229 failed: address already in use 的錯誤。

伺服器啟動後，在 Chrome 中開啟新分頁並訪問 chrome://inspect，您應該會在 Remote Target 區段中看到您的 Next.js 應用程式。點擊應用程式下方的 inspect 以開啟獨立的 DevTools 視窗，然後前往 Sources 分頁。

在此除錯伺服器端程式碼的方式與使用 Chrome DevTools 除錯客戶端程式碼非常相似，只是當您使用 Ctrl+P 或 ⌘+P 搜尋檔案時，您的原始檔路徑會以 webpack://{application-name}/./ 開頭（其中 {application-name} 會根據您的 package.json 檔案替換為您的應用程式名稱）。

在 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 DevTools：除錯 JavaScript