設定您的本機環境

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

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

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

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

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

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

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

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

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

執行 Node 安裝程式

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

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

檢查 Node 和 NPM 的版本

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

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

手動安裝 NPM

若您安裝了不同版本的 NPM,可以手動安裝 6.14.16 版本,步驟如下:

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

多個 Node 版本

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

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

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

在您能夠建立專案並管理部署之前,必須為您的組織啟用 Managed Runtime,而且必須要求存取 Runtime Admin。若 Managed Runtime 尚未啟用,請聯絡您的 Salesforce 客服團隊。若要要求存取 Runtime Admin,請聯絡 Commerce Cloud 管理員,請他們使用 Account Manager 將以下任一角色加到您的帳戶:Managed Runtime UserManaged 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,例如 @v2.0.0@v1.5.2。若您未指定版本,可能會因快取到舊版本而造成意外的結果。

專案預設集

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

  • 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 文件中,也更詳細地說明了設定值。請參閱設定值

設定值更多資訊
Managed Runtime Admin 中的專案 IDManaged Runtime 管理介紹了如何建立專案和查詢現有專案的專案 ID。

範例:example-project
B2C Commerce 執行個體 URL需要新的 B2C Commerce 執行個體來進行開發或測試嗎?請參閱建立 On-Demand Sandbox

範例:https://zzdc-001.sandbox.us01.dx.commercecloud.salesforce.com
Commerce API 用戶端 ID此識別碼再也無法於 Account Manager 中找到。請參閱為 API 存取產生用戶端 ID

範例:1adba44c-ee9b-41f9-b4bf-1bbc3dda1967
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 存取中的指示。

這樣您的本機開發環境就設定完成了,下一步是推送程式碼套件至 Managed Runtime,並使用 Runtime Admin 進行部署。當您可以存取 Runtime Admin 時,您就可以完成「開始使用」系列的最後一篇指南:推送和部署套件