設定您的本機環境

這份指南說明如何設定本機環境，來使用 PWA Kit 進行開發。

我們建議使用以 Unix 為主的作業系統進行 PWA Kit 開發，例如：

Windows 使用者：請參閱 Microsoft 給 Node 開發人員的官方建議。

您必須安裝 Managed Runtime 支援的特定版本 Node 和 Node Package Manager (NPM)。

前往 Node 18.x 下載頁面，為您的裝置下載正確的安裝程式。

Windows 使用者：下載與您的處理器對應的 .msi 檔案。舉例來說，若您擁有 64 位元的 Intel 處理器，則應選擇 x64 安裝程式。

Mac 使用者：下載 .pkg 檔案。

Apple Silicon 使用者：如果您尚未安裝 Rosetta，請執行 softwareupdate --install-rosetta。

Linux 使用者：下載與您的處理器對應的 -linux 檔案。舉例來說，若您擁有 64 位元的 Intel 處理器，則應選擇您偏好的封存格式的 linux-x64 安裝程式。

下載適合的 Node 安裝程式後，請開啟並依照指示完成設定。

當安裝程式提示時，請接受預設選項來同時安裝 Node.js 執行階段、安裝 Node Package Manager，並新增 Node.js 執行階段至您的路徑。

繼續往下之前，請檢查是否安裝了正確的 Node 和 NPM 版本：

  1. 開啟終端機。
  2. 執行 node -v。
  3. 確認傳回的是 v18.16.1 (或最新 18.x 版本)。
  4. 執行 npm -v。
  5. 確認傳回的是 9.5.1 (或 Node 18.x 隨附的最新版本)。

若您安裝了不同版本的 NPM，可以手動安裝 9.5.1 版本，步驟如下：

  1. 開啟終端機。
  2. 執行 npm install -g npm@9.5.1。
  3. 再次執行 npm -v。
  4. 確認傳回的是 9.5.1。

若您希望在 Windows 上管理多個 Node 版本，我們建議使用 Node Version Switcher 或 Volta。我們不建議使用 Corey Butler 的 Node Version Manager (NVM) for Windows，因為我們在測試期間曾遇到問題。

針對 Mac 和 Linux 使用者，我們建議安裝 Node Version Manager。

每個 PWA Kit 網店都必須在 Runtime Admin 中建立一個專案來管理部署。

在使用 Managed Runtime 和 Runtime Admin 之前，必須啟用它們，而且您必須要求其存取權。要為您的組織啟用 Managed Runtime 和 Runtime Admin，請聯絡您的 Salesforce 客服團隊。要進行存取，請要求您的 Commerce Cloud 管理員使用 Account Manager 將以下任一角色加到您的帳戶：Managed Runtime User 或 Managed Runtime Admin。

若您或您的團隊成員尚未在 Runtime Admin 中建立專案，請見以下步驟：

  1. 登入 Runtime Admin。
  2. 按一下 [New Project] (新專案)。
  3. 為專案輸入名稱。
  4. 按一下 [Create Project] (建立專案)。

請記下專案 ID，因為開發時您需要此資訊來產生專案檔案。

首次建立專案時，在部署必要的雲端基礎架構之前，無法在網路上存取該網站。部署流程最多可能需要 40 分鐘。

想進一步瞭解 Runtime Admin 的功能，請參閱我們的 Managed Runtime 管理指南。

大部分 PWA Kit 開發人員一開始會複製內含之前產生的專案檔案的存放庫。(如欲瞭解如何產生新專案，請跳到下一區段。)

複製專案存放庫後，您必須安裝套件相依性：

  1. 開啟終端機。
  2. 變更至專案目錄。
  3. 執行 npm ci

若您已經擁有現成的 PWA Kit 專案，且已完成上一區段的指示，您可以跳到下一區段。否則，您必須產生專案。

若要產生專案，請開啟終端機並執行以下命令。以包含 Runtime Admin 專案 ID 的路徑取代 ~/PLACEHOLDER-PROJECT-ID：

在 npx 命令中，您可以將 @latest 替換為特定版本的 Retail React App，例如 @v3.0.0 或 @v2.7.3。若您未指定版本，可能會因快取到舊版本而造成意外的結果。

當系統提示您選擇專案預設集時，請從以下選項中擇一：

  • retail-react-app-demo：使用 Retail React App 網店範本，並使用示範 Sandbox 作為後端。無需進一步設定。
  • retail-react-app：使用 Retail React App 網店範本，並使用您的 B2C Commerce 執行個體作為後端。您必須提供設定值。

在使用 retail-react-app 預設集時，產生器指令碼會要求您提供幾個設定值。這些設定值會將您的新 PWA Kit 專案與 Runtime Admin 工具中相應的專案、B2C Commerce 執行個體產生關聯。

以下表格提供了關於每個專案設定值和所在位置的詳細資訊。在 B2C Commerce API 文件中，也更詳細地說明了設定值。請參閱基底 URL 和要求格式。

設定值更多資訊
Managed Runtime Admin 中的專案 IDManaged Runtime 管理介紹了如何建立專案和查詢現有專案的專案 ID。
  • 範例：example-project
B2C Commerce 執行個體 URL需要新的 B2C Commerce 執行個體來進行開發或測試嗎？請參閱建立 On-Demand Sandbox。
  • 範例：https://zzdc-001.dx.commercecloud.salesforce.com
Commerce API 用戶端 ID此識別碼再也無法於 Account Manager 中找到。請參閱為 API 存取產生用戶端 ID。
  • 範例：1adba44c-ee9b-41f9-b4bf-1bbc3dda1967
Commerce API 私人用戶端模式這會切換您的應用程式使用公用或私人驗證流程來登入購物者。如需更多資訊，請參閱購物者登入文件和使用 SLAS 私人用戶端。
  • 預設：true
Business Manager 中的網站 ID用於辨識特定電子商務網站的字串。若要獲得 Business Manager 中的可用網站清單及其相關網站 ID，請前往 [管理] > [網站] > [管理網站]。
  • 範例：RefArch
Business Manager 中的 Commerce API 組織 ID用來根據領域和執行個體，辨識您的組織以供 API 存取的字串。若要在 Business Manager 中尋找組織 ID，請前往 [管理] > [網站開發] > [Salesforce Commerce API 設定]。
  • 範例：f_ecom_zzdc_001
Business Manager 中的 Commerce API 短代碼基於路由目的而指派至一個領域的八字元字串。短代碼適用於所有執行個體的整個領域環境。(所有 On-Demand Sandbox 的短代碼均為 kv7kzm78)。若要在 Business Manager 中尋找短代碼，請前往 [管理] > [網站開發] > [Salesforce Commerce API 設定]。
  • 範例：kv7kzm78
Einstein Configurator 中的 API 用戶端 ID請參閱 Commerce Cloud 開發人員的 Einstein API 文件並直接存取 Einstein Configurator。

產生專案後，我們建議您將所產生的專案檔案交付至存放庫，並與您的網店開發人員分享該存放庫。

您可以在專案產生 後 編輯專案的設定值。請參閱設定檔來瞭解更多資訊。

在這些值有所變更時，別忘了更新設定，像是當您自訂專案檔案來在不同的 B2C Commerce 執行個體上運作時。

若要啟動網頁伺服器來進行本機開發，請從專案目錄執行以下命令：

當開發伺服器開始運作後，您可以開啟瀏覽器並預覽您的網店：

您可以使用鍵盤快捷鍵 Control+C 隨時停止開發伺服器。

若要預覽伺服器端轉譯頁面，請在您想預覽的 URL 後附加 ?__server_only 查詢字串。舉例來說，您可以造訪 URL www.example.com?__server_only 來測試 www.example.com 的伺服器端轉譯版本。

  • 複製現有專案並執行 npm ci 或產生新專案後，可能需要等候幾分鐘才會在終端機上看到活動，因此在完成之前請不要取消流程。此外，防毒軟體 (尤其在 Windows 上) 可能會導致安裝時間更久。

  • 若您從 authorize 端點收到 HTTP 401 錯誤回應，則表示 Shopper Login and API Access Service (SLAS) 發生設定問題。若要修正您的 SLAS 設定，請參閱設定 API 存取中的指示。