設定檔

在設定檔中，您可以自訂 PWA Kit 應用程式運作方式的不同層面，包括：API 存取、URL 格式、處理多個網站、要求的 Proxy 處理、伺服器端轉譯。

您可自由選擇以 JavaScript、YAML 或 JSON 編寫設定檔。支援以下副檔名：.js、.yml、.yaml、.json。

使用 Retail React App 範本建立 PWA Kit 專案後，會得到一個設定檔：app/config/default.js。其匯出的設定物件是根據提供給 pwa-kit-create-app 的選項而設定，但您可隨時更新設定。在初始專案產生後，通常需要更新，才能與 B2C Commerce 執行個體的變更保持同步。

為了支援同構轉譯，設定值會序列化到頁面。請勿在您的設定中放置密碼！

您可以使用其他設定檔來替換 default.js 或對其進行補充，因為 PWA Kit 支援特定於環境的設定，本指南稍後將介紹這部分。

讓我們先來檢視 default.js 或任何設定檔中的特定設定物件及屬性。

將您的應用程式與 Managed Runtime 產生關聯的專案字串 並非 設定檔的一部分，但可以在專案目錄根目錄下 package.json 檔案頂端的 name 屬性中找到。初始專案產生後，您可變更 name 的值來符合 Runtime Admin 中看到的專案 ID。

在 PWA Kit 1.5.0 版本之前，這些設定在 app/api.config.js 中。

若要設定對 B2C Commerce API 和 Open Commerce API (OCAPI) 的存取，您可以編輯從設定檔匯出的 app.commerceAPI 物件。

以下是附有註解且包含範例值的程式碼片段：

若要設定對 Einstein API 的存取，您可以編輯 app.einsteinAPI 物件。

以下是另一個附有註解且包含範例值的程式碼片段：

如需進一步瞭解在前述程式碼片段中使用設定物件的 CommerceAPI 分類，請參閱 Retail React App 架構指南。

如需進一步瞭解 Account Manager 和 Business Manager 中的設定任務，以便為 B2C Commerce 執行個體啟用 API 存取，請參閱設定 API 存取指南。

您可以在 app.url 物件中自訂網店 URL 的格式。

根據預設，app.url 物件使用以下值進行設定：

根據這些預設設定，目前的網站和地區設定會在 URL 路徑中顯示。

您可以將 url.locale 設定為下列值之一，以選擇在 URL 中如何顯示 (或不要顯示) 目前的地區設定：

  • path 路徑中包含地區設定。範例：/en-US/women/dress
  • query_param:用查詢參數的方式包含地區設定。範例：/women/dress?locale=en-US
  • none 中不包含地區設定。範例：/women/dress

url.showDefaults:此布林值決定了預設網站或地區設定值是否會在 URL 中顯示。預設為：false。

我們會將為您應用程式設定的網站抽取出來，放到其獨立的檔案，名稱為 config/sites.js。這個檔案將匯入至每個設定檔，並在 app 物件中匯出。將檔案這樣分開，能讓您更輕鬆地同步由應用程式支援的網站，以及由 Business Manager 後端定義的網站。(您也可以選擇直接在設定檔中定義您的網站。)

app 物件也包含管理多重網站及其別名的其他設定。我們的多重網站指南提供了這些設定的詳細資訊。

要求的 Proxy 處理可在 ssrParameters.proxyConfigs 陣列中設定，這在我們的 Proxy 要求指南中有詳細介紹。

在 PWA Kit 1.5.0 版本之前，這些設定在 package.json 中。

以下表格列出了與伺服器端轉譯相關的設定選項：這些選項並非 app 物件的一部分，而是以主要 exports 物件的個別屬性表示。

屬性 描述
ssrParameters.ssrFunctionNodeVersion 決定使用哪一版本的節點來執行應用程式伺服器的字串。

允許的值：16.x。
ssrEnabled 啟用或停用建立伺服器端轉譯必要檔案的布林值。設定此值為 false 已於 2021 年 8 月棄用。
ssrOnly Glob 表達式陣列，在此 * 為萬用字元，可符合零個或多個任意字元的執行個體。

決定哪些檔案專供伺服器端轉譯系統使用，且不可透過 /mobify/bundle/ 路徑使用。

新產生專案的預設為：['ssr.js', 'ssr.js.map', 'node_modules/**/*.*']
ssrShared Glob 表達式陣列，在此 * 為萬用字元，可符合零個或多個任意字元的執行個體。

決定哪些檔案可供伺服器端轉譯系統使用，且可透過 /mobify/bundle/ 路徑使用。

新產生專案的預設為：

您可以在 app/config/ 目錄中包含多個設定檔，包括針對特定環境的設定檔。

特定於環境的設定可以讓您的部署更加高效、靈活。例如，您可以：

  • 將單個套件部署到多個 Managed Runtime 環境，並讓每個環境連接到不同的 B2C Commerce 執行個體。
  • 在本機開發期間連接到您自己的 On-Demand Sandbox，但在部署至 Managed Runtime 時連接到不同的執行個體。

要建立特定於環境的設定檔，請遵循 default.js 中使用的相同慣例，但改以目標環境的名稱作為檔案的基底名稱。可使用任何支援的檔案格式與相對應的副檔名。範例：production.js、staging.json。

PWA Kit 應用程式會透過搜尋 app/config 和詢問以下問題來選擇要載入的正確設定檔，並依照下列順序：

  1. 是否有檔案符合目前在 Managed Runtime 上執行的環境之名稱？
  2. 若為本機執行，是否有名為 local 的檔案，並擁有支援的副檔名？
  3. 若找不到設定檔，是否有名為 default 的檔案，並擁有支援的副檔名？

只要以上任一問題的答案為「是」，PWA Kit 就會停止搜尋，並載入符合該問題答案的檔案。

若兩個檔案擁有相同的基底名稱，但有不同的副檔名，則會選擇擁有最高指派優先順序的副檔名。支援的副檔名依照以下順序指派優先順序，從最高到最低：.js、.yml、.yaml 或 .json。這代表在 default.js 和 default.json 之間，PWA Kit 會載入 default.js，因為其優先順序比較高。