通過 esa.jsonc 部署版本控制的 ESA 頁面 - 邊緣安全加速

Pages可以通過esa.jsonc檔案快速配置構建資訊，並且可自訂不同應用情境下的路由行為。

以esa.jsonc進行Pages構建

在Github中對應的專案根目錄中建立 esa.jsonc 檔案。該檔案允許您定義和覆蓋專案的預設設定，以便更靈活地設定項目。

優勢

基礎設施即代碼 ：配置與您的代碼一同被版本控制，每一次變更都有跡可循。
易於團隊協作：團隊所有成員共用同一份設定檔，確保了本地開發和雲端部署的一致性。
便捷復原：任何時候都可以復原到歷史上的任意一次提交，並精確複現當時的構建環境。

生效優先順序

esa.jsonc 檔案中的配置優先順序大於控制台介面上的配置：

如果您的專案中沒有 esa.jsonc 檔案：
- 您可以在專案的詳情頁面參考如何通過控制台修改基礎配置資訊調整相關構建選項。
- 控制台的配置將作為本次及後續部署的依據。
如果您的專案中存在 esa.jsonc 檔案：
- 系統會自動檢測到該檔案，並將其作為配置的唯一來源。
- 在專案的詳情頁面，所有被 esa.jsonc 管理的配置項將不生效。
- 如需修改配置，必須直接編輯 esa.jsonc 檔案，並將更改推送到您的 Github 倉庫。

配置樣本

在Github中對應的Pages倉庫中新增esa.jsonc檔案，配置樣本可參考：

{
  "name": "vite-react-template",
  "entry": "./src/index.js",
  "installCommand": "npm install",
  "buildCommand": "npm run build",
  "assets": {
    "directory": "./dist",
    "notFoundStrategy": "singlePageApplication"
  }
}

參數	說明
name	指定部署的目標專案。如果該專案已存在，部署將在其下進行；如果不存在，系統將使用此名稱自動為您建立一個新專案。
entry	邊緣函數的入口執行檔案路徑，例如： `./src/index.ts`。
installCommand	配置自訂安裝指令，例如：`npm install`。該配置會覆蓋控制台的安裝命令配置，如果設定成Null 字元串，安裝步驟將被跳過。支援的包管理器包括：npm、pnpm、yarn、cnpm、bun。
buildCommand	配置自訂構建命令，例如：`npm run build`。該配置會覆蓋控制台的構建命令配置，如果設定成Null 字元串，構建步驟將被跳過。
assets	靜態資源託管功能允許開發人員在ESA函數和Pages上運行前端網站。您可以配置資產目錄，每個Pages只能配置一組靜態資源，assets 提供了以下選項： `directory`：構建產物中將被靜態託管的目錄，例如：`./public`、`./dist` 、 `./build`等。 `notFoundStrategy` ：當請求的路徑未匹配到任何靜態資源時，執行的策略。 singlePageApplication：返回靜態託管目錄的`index.html`檔案及 `200 OK`狀態代碼。適用於單頁應用時。 404Page：返回靜態託管目錄的`404.html`檔案及 `404 Not Found` 狀態代碼。說明若您同時配置了函數指令碼與`assets.notFoundStrategy`選項，那麼導航請求將不會觸發該函數指令碼的執行。導航請求：指瀏覽器在使用者直接存取頁面時（例如在地址欄輸入URL或點選連結）自動發出的請求，其特徵是包含了`Sec-Fetch-Mode: navigate`要求標頭。

靜態資源的路由

當完成esa.jsonc檔案配置後，請求的 URL 與靜態資源目錄中的檔案路由結果將會按照以下情境進行:

預設模式

當在esa.jsonc中未配置notFoundStrategy欄位時，如：

{
  "name": "vite-react-template",
  "entry": "./src/index.js",
  "assets": {
    "directory": "./dist"
  }
}

ESA將根據下述流程進行路由：

用戶端請求URL到達邊緣節點時，將會判斷是否有對應的靜態資源：若有，則直接響應對應靜態檔案；若無，則繼續判斷2。
判斷是否有ER函數指令碼：若有，則執行ER函數指令碼；若無，則響應404 Not Found。

單頁應用

當您構建的應用為單頁應用類型，可以在esa.jsonc中配置notFoundStrategy欄位為 singlePageApplication 模式，如：

{
  "name": "vite-react-template",
  "entry": "./src/index.js",
  "assets": {
    "directory": "./dist",
    "notFoundStrategy": "singlePageApplication"
  }
}

ESA將根據下述流程進行路由：

用戶端請求URL到達邊緣節點時，將會判斷是否有對應的靜態資源：若有，則直接響應對應靜態檔案；若無，則繼續判斷2。
判斷是否為導航請求（要求標頭攜帶Sec-Fetch-Mode: navigate）：若否，則繼續判斷3；若是，則將請求路由至/index.html檔案，繼續判斷a：
1. 判斷是否存在index HTML頁面：若有，則響應200 OK並且返回/index.html內容；若無，則繼續判斷3。
判斷是否有ER函數指令碼：若有，則執行ER函數指令碼；若無，則響應404 Not Found。

靜態網站產生

當您構建的應用為靜態網站組建類型，可以在esa.jsonc中配置notFoundStrategy欄位為 404Page 模式，如：

{
  "name": "vite-react-template",
  "entry": "./src/index.js",
  "assets": {
    "directory": "./dist",
    "notFoundStrategy": "404Page"
  }
}

ESA將根據下述流程進行路由：

用戶端請求URL到達邊緣節點時，將會判斷是否有對應的靜態資源：若有，則直接響應對應靜態檔案；若無，則繼續判斷2。
判斷是否為導航請求（要求標頭攜帶Sec-Fetch-Mode: navigate）：若否，則繼續判斷3；若是，則將請求路由至/404.html檔案，繼續判斷a：
1. 判斷是否存在404 HTML頁面：若有，則響應200 OK並且返回/404.html內容；若無，則繼續判斷3。
判斷是否有ER函數指令碼：若有，則執行ER函數指令碼；若無，則響應404 Not Found。

如何通過控制台修改基礎配置資訊？

登入ESA控制台，在左側導覽列選擇邊緣計算 > 函數和Pages。
在函數和Pages頁面，單擊目標函數或Pages。
選擇基本資料頁簽，在構建資訊，單擊修改。

根據業務需求，變更構建資訊。

參數	說明
根目錄	構建命令將在此目錄下執行，預設`/`。若是`monorepo`，請填寫要構建的子專案路徑（例如 `/frontend`或 `/packages/web`）。
靜態資源目錄	構建產物中將被靜態託管的目錄，例如：`./public`、`./dist` 或 `./build`。您可以在esa.jsonc檔案的`assets.directory`欄位中指定靜態資源目錄。該配置的優先順序高於構建資訊中的配置，會覆蓋您在此處的配置。
函數檔案路徑	函數的入口檔案路徑，即實際執行的檔案。例如：`./src/index.ts`。您可以在esa.jsonc檔案的`entry`欄位中指定函數檔案路徑。該配置的優先順序高於構建資訊中的配置，會覆蓋您在此處的配置。
Node.js版本	構建使用的 Node.js 版本。修改該配置後，需要重新觸發構建才會生效。您可以在`package.json`檔案的`engines.node`欄位中指定Node.js主要版本。該配置的優先順序高於構建資訊中的配置，會覆蓋您在此處的配置。
環境變數	設定構建過程中可使用的環境變數，可以通過全域對象`process.env`擷取。