PWA Kit 應用程式偵錯

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

將本指南中的任何預留位置替換為實際值。預留位置的格式為：$PLACEHOLDER

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

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

  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 的這份指南：偵錯 JavaScript。

  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 伺服器。

有三種方法可以偵錯部署到 Managed Runtime (MRT) 的程式碼：

  • 使用原始碼對應檔來找出發生錯誤的位置。
  • 追蹤記錄檔以在低流量環境中解決即時問題或錯誤。
  • 對於 Production 環境，請使用 Log Center，它提供強大的搜尋和保留功能。

使用原始碼對應檔來找出任何伺服器端或用戶端錯誤。原始碼對應檔提供了簡單的錯誤堆疊追蹤，可以精確定位錯誤發生的位置。例如，堆疊追蹤可找出發生錯誤的檔案和行號，以便更輕鬆地進行疑難排解。

啟用原始碼對應檔會影響效能，因此我們建議僅在非 Production 環境中使用此功能。

若要使用原始碼對應檔，必須使用 PWA Kit 版本 3.4.x 或更高版本產生網站。如果您的版本較舊，請升級專案以使用 PWA Kit 3.4.x。

您有兩個選擇來啟用原始碼對應檔：使用 Runtime Admin 或使用 Managed Runtime API。

使用 Runtime Admin

  1. 登入 Runtime Admin。
  2. 按一下您的專案。
  3. 按一下環境。
  4. 按一下 [Environment Settings] (環境設定)。
  5. 在 [Advanced] (進階) 部分，按一下 [Edit] (編輯)。
  6. 啟用 [Source Maps].(原始碼對應檔)。
  7. 在 Advanced (進階) 部分的頂部，按一下 Update (更新)。
  8. 等待套件完成重新部署。

使用 Managed Runtime API

呼叫 projects_target_partial_update API 端點並將 enable_source_maps 設為 true。這會將環境中的 NODE_OPTIONS Managed Runtime 環境變數設定為 --enable-source-maps 並重新部署該套件。

  1. 當您建置專案時，請使用下列本機環境變數產生 ssr.js.map 檔案：PWA_KIT_SSR_SOURCE_MAP=true。
  1. 將您的套件部署到 Managed Runtime。

啟用並上傳原始碼對應檔後，您可以在 Managed Runtime 上使用 Tail Logs 進行查看。

使用原始碼對應檔可能會導致效能問題。例如，每次存取 error.stack 時都會有延遲。因此，當程式碼中包含 console.error(e) 時，這可能會導致網站變慢。

  • 新的非 Production 環境：enable_source_maps 設為 true。
  • 新的 Production 環境：enable_source_maps 設為 false。此行為有助於避免啟用原始碼對應檔功能時，可能出現的潛在效能影響。
  • 所有預先存在的環境：enable_source_maps 設為 false。

當您的應用程式被部署至 Managed Runtime 時，不支援遠端偵錯。但是，您可以即時追蹤任何 Managed Runtime 環境的記錄檔，以協助診斷任何伺服器端的錯誤。

您有兩個選項可以透過命令列來追蹤記錄檔。

如果您是在產生自 2.4.1 或以上版本的 PWA Kit 專案之內工作，則您可以：

  • 查看關於記錄檔命令的說明：npm run tail-logs -- --help
  • 追蹤某一特定專案和環境的記錄檔：npm run tail-logs -- --environment $ENV_ID

上述命令中，額外的 -- 為必要。

如果您是在 PWA Kit 專案之外工作，或是專案產生自低於 2.4.1 的版本，您可以使用 npx 來執行以下動作：

  • 查看關於記錄檔命令的說明：npx @salesforce/pwa-kit-dev tail-logs --help
  • 追蹤某一特定環境 ID 和專案 ID 的記錄檔：npx @salesforce/pwa-kit-dev tail-logs --environment $ENV_ID --project $PROJ_ID

除了 --environment 和 --project 引數，您也可以使用較短的 -e 和 -p 引數。

追蹤記錄檔時，請記得以下限制：

  • 每個記錄檔追蹤工作階段將在 60 分鐘後終止。
  • 在同一時間、包括所有使用者在內，每個環境可支援最多 100 個有效的記錄檔追蹤工作階段。
  • 若要追蹤記錄檔，您需要擁有對 Managed Runtime 專案的開發人員或管理員的使用者權限。

如果您使用 PWA Kit 建置網站或擁有 B2C Commerce 執行個體，請使用 Log Center 來進行疑難排解。Log Center：

  • 提供從 Managed Runtime (MRT) 和 B2C Commerce 執行個體存取記錄檔的單一位置。將 MRT 環境中的事件與 B2C Commerce 執行個體的情況連接。
  • 可讓您搜尋並篩選許多歷史記錄檔。您可以獲得有關 Production 中發生的情況的更多資訊，協助更快地調查與解決問題。
  • Log Center 中的 MRT 記錄檔僅適用於 Production 環境。請參閱先決條件。
  • 從事件發生到記錄檔出現在 Log Center 中，最多可能有 15 分鐘的延遲。

本指南的重點在於對使用 PWA Kit 建置的網站進行偵錯。想瞭解如何將 Log Center 與您的 B2C Commerce 執行個體結合使用，請參閱集中式 Log Center。

要在 Log Center 中存取某個環境的 MRT 記錄檔，您必須先：

  1. 在 Account Manager 中具有 Log Center User 角色。如要驗證，請檢查您在 Account Manager 中的角色。如果您沒有該角色，請要求您的 Account Manager 管理員授予您存取權限。請參閱為 Salesforce B2C Commerce 使用者管理 Account Manager。

  2. 如下所示，設定環境：

    a.將環境標記為 Production 環境。請參閱與 Production 環境相關的詳細資料和限制。

    b.選擇要連接到環境的 Commerce Cloud (B2C Commerce) 執行個體。

    c.新增一或多個網站 ID 來與環境連結。

完成先決條件後，若要在 Log Center 中查看 MRT 記錄檔：

  1. 啟動 Log Center。
  2. 選擇地區。
  3. 選擇**領域**。若您不知道領域 ID，請洽詢您的業務專員 (AE) 或 Customer Success Manager (CSM)。
  4. 按一下 [顯示篩選結果]。
  5. 按一下 [搜尋] > [目前搜尋]。
  6. 在「服務類型」下方，選擇 [mrt]。
  7. 在「主機」下方，選擇您想要查看其 MRT 記錄檔的 Production 環境。主機格式為 $PROJECT.$ENVIRONMENT。如果您有多個 MRT Production 環境，則可以看到多個 MRT 主機名稱。
  8. 查看 MRT 記錄檔。

想瞭解 Log Center 的記錄檔層級和記錄量，請參閱管理員設定。