文件AEMAEM 教學課程AEM as a Cloud Service 教學課程

自訂錯誤頁面

Last update: Wed Sep 25 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

建立對象：

  • 初學者
  • 中繼
  • 開發人員

瞭解如何為您的AEM as a Cloud Service託管網站實施作業自訂錯誤頁面。

在本教學課程中，您將學習：

  • 預設錯誤頁面

  • 提供錯誤頁面的來源

    • AEM服務型別 — 作者、發佈、預覽
    • Adobe管理的CDN

  • 自訂錯誤頁面的選項

    • ErrorDocument Apache指示詞
    • ACS AEM Commons — 錯誤頁面處理常式
    • CDN錯誤頁面

預設錯誤頁面

讓我們檢閱何時顯示錯誤頁面、預設錯誤頁面，以及提供這些頁面的來源。

發生下列情況時會顯示錯誤頁面：

  • 頁面不存在(404)
  • 未獲存取頁面的授權(403)
  • 發生伺服器錯誤(500)，因為程式碼問題或伺服器無法連線。

AEM as a Cloud Service為上述案例提供​ 預設錯誤頁面。 這是一般頁面，不符合您的品牌。

預設錯誤頁面​ 從 AEM服務型別​ （作者、發佈、預覽）或 Adobe管理的CDN 提供。 如需詳細資訊，請參閱下表。

錯誤頁面提供自
詳細資料
AEM服務型別 — 作者、發佈、預覽
當AEM服務型別提供頁面要求，且發生任何上述錯誤案例時，會從AEM服務型別提供錯誤頁面。
Adobe管理的CDN
當Adobe管理的CDN 無法連線到AEM服務型別 （原始伺服器）時，會從Adobe管理的CDN提供錯誤頁面。 這是不太可能發生但值得規劃的事件。

例如，AEM服務型別和Adobe管理的CDN提供的預設錯誤頁面如下：

預設AEM錯誤頁面

不過，您可以​ 自訂AEM服務型別和Adobe管理的 CDN錯誤頁面，以符合您的品牌，並提供更佳的使用者體驗。

自訂錯誤頁面的選項

下列選項可用於自訂錯誤頁面：

適用於
選項名稱
說明
AEM服務型別 — 發佈和預覽
ErrorDocument指示詞
使用Apache設定檔案中的ErrorDocument指示詞來指定自訂錯誤頁面的路徑。 僅適用於AEM服務型別 — 發佈和預覽。
AEM服務型別 — 作者、發佈、預覽
ACS AEM Commons錯誤頁面處理常式
使用ACS AEM Commons錯誤頁面處理常式來自訂所有AEM服務型別的錯誤。
Adobe管理的CDN
CDN錯誤頁面
當Adobe管理的CDN無法連線AEM服務型別（原始伺服器）時，請使用CDN錯誤頁面來自訂錯誤頁面。

先決條件

在本教學課程中，您將學習如何使用​ ErrorDocument ​指示詞、ACS AEM Commons Error Page Handler ​和​ CDN Error Pages ​選項來自訂錯誤頁面。 若要按照本教學課程進行學習，您需要：

設定

  • 請依照下列步驟，複製AEM WKND專案並將其部署至本機AEM開發環境：

    code language-none 
    # For local AEM development environment
$ git clone git@github.com:adobe/aem-guides-wknd.git
$ cd aem-guides-wknd
$ mvn clean install -PautoInstallSinglePackage -PautoInstallSinglePackagePublish

  • 針對AEM as a Cloud Service環境，請執行完整棧疊管道以部署AEM WKND專案，請參閱非生產管道範例。

  • 確認WKND網站頁面可正確轉譯。

ErrorDocument Apache指示詞以自訂AEM提供的錯誤頁面 errordocument

若要自訂AEM提供的錯誤頁面，請使用ErrorDocument Apache指示詞。

在AEM as a Cloud Service中，ErrorDocument Apache指示詞選項僅適用於發佈和預覽服務型別。 它不適用於作者服務型別，因為Apache + Dispatcher不屬於部署架構的一部分。

讓我們檢閱AEM WKND專案如何使用ErrorDocument Apache指示詞來顯示自訂錯誤頁面。

  • ui.content.sample模組包含品牌化錯誤頁面 @ /content/wknd/language-masters/en/errors。 在您的本機AEM或AEM as a Cloud Service https://author-p<ID>-e<ID>.adobeaemcloud.com/ui#/aem/sites.html/content/wknd/language-masters/en/errors環境中檢閱這些專案。

  • 來自dispatcher模組的wknd.vhost檔案包含：

    code language-none 
    ...
# ErrorDocument directive in wknd.vhost file
ErrorDocument 404 ${404_PAGE}
ErrorDocument 500 ${500_PAGE}
ErrorDocument 502 ${500_PAGE}
ErrorDocument 503 ${500_PAGE}
ErrorDocument 504 ${500_PAGE}

...
# DispatcherPassError value in wknd.vhost file
<IfModule disp_apache2.c>
    ...
    DispatcherPassError        1
</IfModule>

# Custom error pages path in custom.vars file
Define 404_PAGE /content/wknd/us/en/errors/404.html
Define 500_PAGE /content/wknd/us/en/errors/500.html
...

  • 在您的環境中輸入不正確的頁面名稱或路徑，檢閱WKND網站的自訂錯誤頁面，例如https://publish-p105881-e991000.adobeaemcloud.com/us/en/foo/bar.html。

ACS AEM Commons-Error頁面處理常式，可自訂AEM提供的錯誤頁面 acs-aem-commons

若要在​ 所有AEM服務型別 ​中自訂AEM提供的錯誤頁面，您可以使用ACS AEM Commons Error Page Handler選項。

。如需詳細的逐步指示，請參閱如何使用區段。

用於自訂CDN伺服錯誤頁面的CDN錯誤頁面 cdn-error-pages

若要自訂Adobe管理的CDN所提供的錯誤頁面，請使用CDN錯誤頁面選項。

讓我們實作CDN錯誤頁面，以在Adobe管理的CDN無法連線AEM服務型別（原始伺服器）時自訂錯誤頁面。

IMPORTANT
Adobe管理的CDN無法連線到AEM服務型別 （原始伺服器）是​ 不可能的事件，但值得規劃。

實作CDN錯誤頁面的高層級步驟為：

  • 將自訂錯誤頁面內容開發為單頁應用程式(SPA)。
  • 將CDN錯誤頁面所需的靜態檔案託管在公開可存取的位置。
  • 設定CDN規則(errorPages)並參考上述靜態檔案。
  • 使用Cloud Manager管道將已設定的CDN規則部署到AEM as a Cloud Service環境。
  • 測試CDN錯誤頁面。

CDN錯誤頁面概觀

CDN錯誤頁面會由Adobe管理的CDN實作為單頁應用程式(SPA)。 由Adobe管理的CDN所傳送的SPAHTML檔案包含最低限度的HTML片段。 自訂錯誤頁面內容是使用JavaScript檔案動態產生。 必須在客戶可公開存取的位置開發及託管JavaScript檔案。

Adobe管理的CDN所傳送的HTML片段結構如下：

<!DOCTYPE html>
<html lang="en">
  <head>

    ...

    <title>{title}</title>
    <link rel="icon" href="{icoUrl}">
    <link rel="stylesheet" href="{cssUrl}">
  </head>
  <body>
    <script src="{jsUrl}"></script>
  </body>
</html>

HTML片段包含以下預留位置：

  1. jsUrl： JavaScript檔案的絕對URL，可透過動態建立HTML元素來呈現錯誤頁面內容。
  2. cssUrl：設定錯誤頁面內容樣式的CSS檔案絕對URL。
  3. icoUrl： Favicon的絕對URL。

開發自訂錯誤頁面

讓我們將WKND特定的品牌錯誤頁面內容開發為單頁應用程式(SPA)。

為了示範，請使用React，不過您可以使用任何JavaScript架構或資料庫。

  • 執行下列命令，建立新的React專案：

    code language-none 
    $ npx create-react-app aem-cdn-error-page

  • 在您最愛的程式碼編輯器中開啟專案，並更新下列檔案：

    • src/App.js：它是呈現錯誤頁面內容的主要元件。

      code language-javascript 
      import logo from "./wknd-logo.png";
import "./App.css";

function App() {
  return (
    <>
      <div className="App">
        <div className="container">
        <img src={logo} className="App-logo" alt="logo" />
        </div>
      </div>
      <div className="container">
        <div className="error-code">CDN Error Page</div>
        <h1 className="error-message">Ruh-Roh! Page Not Found</h1>
        <p className="error-description">
          We're sorry, we are unable to fetch this page!
        </p>
      </div>
    </>
  );
}

export default App;

    • src/App.css：設定錯誤頁面內容的樣式。

      code language-css 
      .App {
  text-align: left;
}

.App-logo {
  height: 14vmin;
  pointer-events: none;
}


body {
  margin-top: 0;
  padding: 0;
  font-family: Arial, sans-serif;
  background-color: #fff;
  color: #333;
  display: flex;
  justify-content: center;
  align-items: center;
}

.container {
  text-align: letf;
  padding-top: 10px;
}

.error-code {
  font-size: 4rem;
  font-weight: bold;
  color: #ff6b6b;
}

.error-message {
  font-size: 2.5rem;
  margin-bottom: 10px;
}

.error-description {
  font-size: 1rem;
  margin-bottom: 20px;
}

    • 將wknd-logo.png檔案新增至src資料夾。 將檔案復製為wknd-logo.png。

    • 將favicon.ico檔案新增至public資料夾。 將檔案復製為favicon.ico。

    • 執行專案以驗證WKND品牌CDN錯誤頁面內容：

      code language-none 
      $ npm start

      開啟瀏覽器並導覽至http://localhost:3000/以檢視CDN錯誤頁面內容。

    • 建置專案以產生靜態檔案：

      code language-none 
      $ npm run build

      靜態檔案產生於build資料夾中。

或者，您也可以下載包含上述React專案檔案的aem-cdn-error-page.zip檔案。

接著，將以上靜態檔案託管於可公開存取的位置。

CDN錯誤頁面所需的主機靜態檔案

讓我們在Azure Blob儲存體中託管靜態檔案。 不過，您可以使用任何靜態檔案託管服務，例如Netlify、Vercel或AWS S3。

  • 請依照官方Azure Blob儲存體檔案操作，建立容器並上傳靜態檔案。

    note important
    IMPORTANT
    如果您使用其他靜態檔案託管服務，請依照其檔案託管靜態檔案。

  • 請確定靜態檔案可公開存取。 我的WKND示範特定儲存體帳戶設定如下：

    • 儲存體帳戶名稱： aemcdnerrorpageresources
    • 容器名稱： static-files

    Azure Blob儲存體

  • 在上述static-files容器中，已上傳build資料夾中的以下檔案：

    • error.js： build/static/js/main.<hash>.js檔案已重新命名為error.js和可公開存取。
    • error.css： build/static/css/main.<hash>.css檔案已重新命名為error.css和可公開存取。
    • favicon.ico： build/favicon.ico檔案已依原樣上傳，且可公開存取。

接下來，設定CDN規則(errorPages)並參考上述靜態檔案。

設定CDN規則

讓我們設定使用上述靜態檔案來呈現CDN錯誤頁面內容的errorPages CDN規則。

  1. 從AEM專案的主要config資料夾開啟cdn.yaml檔案。 例如，WKND專案的cdn.yaml檔案。

  2. 將下列CDN規則新增至cdn.yaml檔案：

    code language-yaml 
    kind: "CDN"
version: "1"
metadata:
  envTypes: ["dev", "stage", "prod"]
data:
  # The CDN Error Page configuration.
  # The error page is displayed when the Adobe-managed CDN is unable to reach the origin server.
  # It is implemented as a Single Page Application (SPA) and WKND branded content must be generated dynamically using the JavaScript file
  errorPages:
    spa:
      title: Adobe AEM CDN Error Page # The title of the error page
      icoUrl: https://aemcdnerrorpageresources.blob.core.windows.net/static-files/favicon.ico # The PUBLIC URL of the favicon
      cssUrl: https://aemcdnerrorpageresources.blob.core.windows.net/static-files/error.css # The PUBLIC URL of the CSS file
      jsUrl: https://aemcdnerrorpageresources.blob.core.windows.net/static-files/error.js # The PUBLIC URL of the JavaScript file

  3. 儲存、提交變更，並將其推送至Adobe上游存放庫。

部署CDN規則

最後，透過Cloud Manager管道將已設定的CDN規則部署至AEM as a Cloud Service環境。

  1. 在Cloud Manager中，導覽至​ 管道 ​區段。

  2. 建立新管道或選取僅部署​ Config ​檔案的現有管道。 如需詳細步驟，請參閱建立設定管道。

  3. 按一下​ 執行 ​按鈕以部署CDN規則。

部署CDN規則

測試CDN錯誤頁面

若要測試CDN錯誤頁面，請遵循以下步驟：

  • 開啟瀏覽器並導覽至Publish環境URL，將cdnstatus?code=404附加至URL (例如，https://publish-p105881-e991000.adobeaemcloud.com/cdnstatus?code=404)或使用自訂網域URL進行存取

    WKND - CDN錯誤頁面

  • 支援的程式碼為：403、404、406、500和503。

  • 驗證瀏覽器網路索引標籤，以檢視從Azure Blob儲存體載入的靜態檔案。 Adobe管理的CDN所傳送的HTML檔案包含最低限度的內容，而JavaScript檔案會動態建立標示為的錯誤頁面內容。

    CDN錯誤頁面網路標籤

摘要

在本教學課程中，您已瞭解提供錯誤頁面的預設錯誤頁面，以及自訂錯誤頁面的選項。 您已瞭解如何使用ErrorDocument Apache指示詞、ACS AEM Commons Error Page Handler和CDN Error Pages選項來實作自訂錯誤頁面。

其他資源

recommendation-more-help
4859a77c-7971-4ac9-8f5c-4260823c6f69