設定您的本機環境
這份指南說明如何設定本機環境,來使用 PWA Kit 進行開發。
我們建議使用以 Unix 為主的作業系統進行 PWA Kit 開發,例如:
- 安裝了 Windows Subsystem for Linux 的 Windows 10
- macOS 10.13 或以上版本
- Ubuntu Linux 18.x 或以上版本
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 版本:
- 開啟終端機。
- 執行
node -v
。 - 確認傳回的是
v18.16.1
(或最新18.x
版本)。 - 執行
npm -v
。 - 確認傳回的是
9.5.1
(或 Node18.x
隨附的最新版本)。
若您安裝了不同版本的 NPM,可以手動安裝 9.5.1
版本,步驟如下:
- 開啟終端機。
- 執行
npm install -g npm@9.5.1
。 - 再次執行
npm -v
。 - 確認傳回的是
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 中建立專案,請見以下步驟:
- 登入 Runtime Admin。
- 按一下 [New Project] (新專案)。
- 為專案輸入名稱。
- 按一下 [Create Project] (建立專案)。
請記下專案 ID,因為開發時您需要此資訊來產生專案檔案。
首次建立專案時,在部署必要的雲端基礎架構之前,無法在網路上存取該網站。部署流程最多可能需要 40 分鐘。
想進一步瞭解 Runtime Admin 的功能,請參閱我們的 Managed Runtime 管理指南。
大部分 PWA Kit 開發人員一開始會複製內含之前產生的專案檔案的存放庫。(如欲瞭解如何產生新專案,請跳到下一區段。)
複製專案存放庫後,您必須安裝套件相依性:
- 開啟終端機。
- 變更至專案目錄。
- 執行
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 中的專案 ID | Managed Runtime 管理介紹了如何建立專案和查詢現有專案的專案 ID。
|
B2C Commerce 執行個體 URL | 需要新的 B2C Commerce 執行個體來進行開發或測試嗎?請參閱建立 On-Demand Sandbox。
|
Commerce API 用戶端 ID | 此識別碼再也無法於 Account Manager 中找到。請參閱為 API 存取產生用戶端 ID。
|
Commerce API 私人用戶端模式 | 這會切換您的應用程式使用公用或私人驗證流程來登入購物者。如需更多資訊,請參閱購物者登入文件和使用 SLAS 私人用戶端。
|
Business Manager 中的網站 ID | 用於辨識特定電子商務網站的字串。若要獲得 Business Manager 中的可用網站清單及其相關網站 ID,請前往 [管理] > [網站] > [管理網站]。
|
Business Manager 中的 Commerce API 組織 ID | 用來根據領域和執行個體,辨識您的組織以供 API 存取的字串。若要在 Business Manager 中尋找組織 ID,請前往 [管理] > [網站開發] > [Salesforce Commerce API 設定]。
|
Business Manager 中的 Commerce API 短代碼 | 基於路由目的而指派至一個領域的八字元字串。短代碼適用於所有執行個體的整個領域環境。(所有 On-Demand Sandbox 的短代碼均為 kv7kzm78 )。若要在 Business Manager 中尋找短代碼,請前往 [管理] > [網站開發] > [Salesforce Commerce API 設定]。
|
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 存取中的指示。