PWA Kit 應用程式偵錯

錯誤和效能瓶頸是網路應用程式開發過程中無可避免的一部分。透過 PWA Kit,您可以利用各種工具和技術仔細檢驗您的應用程式,徹底探究這些問題。

在您採用這份指南針對特定問題的建議之前,請先嘗試這些一般性的疑難排解步驟:

  • 啟動本機開發伺服器前,請再次確認您正在執行支援的 Node 版本 (請參照開始使用指南)。
  • 確認您的開發伺服器運作正常,且通訊埠並未由另一程序佔據。
  • 在變更程式碼後,請先確認終端機上有出現訊息 HTTP development server listening,再重新載入瀏覽器。
  • 在瀏覽器主控台和終端機中尋找錯誤。
  • 使用瀏覽器的開發人員工具尋找網路錯誤回應。(在 Chrome 的 DevTools 中,前往 [網路] 分頁。)
  • 如需協助辨識語法錯誤和錯字,請執行程式碼格式工具和 linter。Retail React App 中提供了 Prettier (程式碼格式工具) 和 ESLint (linter) 的設定檔。
  • 檢查您的電腦防毒軟體和防火牆設定,確認是否有任何問題導致程式碼無法正常執行或阻擋了網路要求。
  • 若要辨識並分析效能問題,請使用 Chrome DevTools 中的 Profiler 工具。如需更多資訊,請參閱 Google 的這份指南:Analyze Runtime Performance (分析執行階段效能)。您也可以安裝適用於 Chrome 的 React Developer Tools 擴充功能,這樣能獲得另一個 Profiler 分頁,在元件層級檢視類似的資訊。

您可以將兩個特殊的查詢參數新增到商務應用程式提供的任何 URL 中,來協助偵錯伺服器端程式碼的問題。

__server_only 查詢參數會停止 Hydration 流程,讓此頁面在瀏覽器中呈現的方式與伺服器端轉譯後的完全相同。查看頁面的伺服器端轉譯版本不僅能協助進行伺服器端轉譯問題的疑難排解,也能疑難排解 SEO 的問題,因為搜尋引擎會檢索此版本的頁面。

__pretty_print 查詢參數會新增格式至 __PRELOADED_STATE__ 物件,讓其更容易閱讀。此物件在 Hydration 開始前,會提供應用程式狀態的快照,可協助進行偵錯,查看當中是否包含您所預期的值。如要檢視此物件的內容,請載入您的應用程式、檢視此頁面的來源,並搜尋 __PRELOADED_STATE__

__PRELOADED_STATE__ 物件包含在 <script> 標記內,就位於應用程式開始在伺服器端執行時最初要求的頁面 HTML 來源當中。__PRELOADED_STATE__ 物件包含序號化的值,此值由 getProps 函式 (包含附加在 _app 元件和頁面元件的 getProps 版本) 所傳回。

根據預設,應用程式伺服器會在終端機顯示主控台訊息,但無法讓您觀察程式碼的執行情形。這樣的限制可能讓您難以在伺服器端 (或在您的本機機器上) 針對轉譯頁面進行程式碼偵錯。

若要進行進階偵錯,您可以使用不同的命令開啟您的本機開發伺服器,在 Node 中執行可附加偵錯工具的檢查流程。(如需更多詳細資料,請參見 Node 文件。)

您可以將許多熱門瀏覽器和文字編輯器內的偵錯工具附加至 Node 的檢查流程中。以下是 Google Chrome 和 Visual Studio Code 的相關指示。

Google Chrome

  1. 開啟終端機。
  2. 前往您的專案目錄。
  3. 使用 npm run start:inspect 開啟您的本機 dev 伺服器。
  4. 若要確認偵錯工具是否正在聆聽,請在終端機輸出中尋找「Debugger listening」訊息。
  5. 開啟 Chrome 並輸入 URL chrome://inspect。
  6. 按一下 [Open dedicated DevTools for Node] (打開節點專用的 DevTools)。
  7. DevTools 會在新視窗中開啟。
  8. 若要確認是否已附加偵錯工具,請在終端機輸出中尋找「Debugger attached」訊息。
  9. 設定中斷點,新增 debugger 陳述式等。
  10. 在 Chrome 上從您的本機開發伺服器載入頁面。
  11. 使用專用視窗進行偵錯。

現在您可以追蹤伺服器端程式碼的執行了!

想進一步瞭解如何在 DevTools 中使用中斷點來進行偵錯,請參閱 Google 的這份指南:Debug JavaScript (偵錯 JavaScript)。

Visual Studio Code

  1. 在 Visual Studio Code 中開啟您的專案檔案。
  2. 在選單列按一下 [Terminal] (終端機) > [New Terminal] (新終端機)。
  3. 使用 npm run start:inspect 開啟您的本機 dev 伺服器。
  4. 開啟 Command Palette。Windows 捷徑:Ctrl + Shift + P。Mac 捷徑:Command + Shift + P
  5. 輸入以下命令:「Debug: Attach to Node Process」。
  6. 出現 Node 程序清單。選擇清單的第一項。
  7. 若要確認是否已附加偵錯工具,請在終端機輸出中尋找「Debugger Attached」訊息。
  8. 設定中斷點,新增偵錯陳述式等。
  9. 在您的網頁瀏覽器上從本機開發伺服器載入頁面。
  10. 使用 Visual Studio Code 中已整合的偵錯工具進行偵錯。

現在您可以在 Visual Studio Code 中追蹤伺服器端程式碼的執行了!

若要避免重複附加 Node 程序的麻煩,請開啟 Command Palette 並輸入「Debug: Toggle Auto Attach」。切換設定至 Always (總是),並在 Visual Studio Code 終端機中重新啟動本機 dev 伺服器。