測試和偵錯 Lambda@Edge 函數 - Amazon CloudFront
測試您的 Lambda@Edge 函數識別 CloudFront 中的 Lambda@Edge 函數錯誤故障診斷無效的 Lambda@Edge 函數回應 （驗證錯誤）故障診斷 Lambda@Edge 函數執行錯誤 判斷 Lambda@Edge 區域判斷您的帳戶是否將日誌推送至 CloudWatch

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

測試和偵錯 Lambda@Edge 函數

單獨測試您 Lambda@Edge 函數的程式碼，和進行整合測試，這些動作非常地重要，前者可確保函數能夠完成預期的任務，後者則可確保函數能夠正確地搭配 CloudFront 使用。

在整合測試期間，或是在已經部署函數之後，您可能會需要進行 CloudFront 錯誤的偵錯，例如 HTTP 5xx 錯誤。錯誤可能是從 Lambda 函數傳回的無效回應、觸發函數時的執行錯誤，或是由於 Lambda 服務進行調節所產生的錯誤。本主題中的段落，說明了用來判斷是哪些故障類型造成問題的策略，以及您可採取的問題修正步驟。

注意

當您在疑難排解錯誤時檢閱 CloudWatch 日誌檔案或指標時，請注意這些檔案或指標會顯示在最 AWS 區域 接近函數執行位置的位置。因此，如果您有網站或 Web 應用程式與英國的使用者，而且您有與您的分佈相關聯的 Lambda 函數，則必須變更區域以檢視倫敦的 CloudWatch 指標或日誌檔案 AWS 區域。如需詳細資訊，請參閱 判斷 Lambda@Edge 區域。

測試您的 Lambda@Edge 函數

測試您的 Lambda 函數包括兩個步驟：獨立測試和整合測試。

測試獨立的功能

在將您的 Lambda 函數新增到 CloudFront 之前，請務必先使用 CloudFront 主控台中的測試函數，或利用其他的方法，來進行函數的測試。如需在 Lambda 主控台中測試的詳細資訊，請參閱《 AWS Lambda 開發人員指南》中的使用主控台叫用 Lambda 函數。

在 CloudFront 中測試函數的運作

完成整合測試非常地重要，這項測試會建立您的函數與分佈的關聯，並根據 CloudFront 事件執行。請務必以正確的事件觸發函數，並傳回對 CloudFront 有效且正確的回應。例如，請確定事件結構正確、只包含有效的標頭，以此類推。

當您在 Lambda 主控台中，重複地進行函數的整合測試時，請參閱 Lambda@Edge 教學課程中的步驟，以修改程式碼，或變更呼叫函數的 CloudFront 觸發條件。例如，請確定您使用函式的編號版本，如教學課程的這項步驟中所述：步驟 4：新增一個 CloudFront 觸發條件來執行該函數。

在變更和部署函數時，請注意，更新的函數與 CloudFront 觸發條件複寫到所有區域時，將需要幾分鐘的時間。這通常需要幾分鐘的時間，但最多可能需要 15 分鐘。

若要檢查複寫是否已完成，請移至 CloudFront主控台並檢視您的分佈。

檢查您的複寫是否已完成部署

  1. 在 https://console.aws.amazon.com/cloudfront/v4/home 中開啟 CloudFront 主控台。

  2. 選擇分佈名稱。

  3. 檢查分佈的狀態是否已從 In Progress (進行中) 變回 Deployed (已部署)，這表示您的函數已複寫完成。接著，請依照下一節的步驟來驗證函數是否正常運作。

請注意，在主控台中進行的測試只會驗證您的函數邏輯，並不會套用 Lambda@Edge 特定的服務配額 (先前稱為限制)。

識別 CloudFront 中的 Lambda@Edge 函數錯誤

確認您的函數邏輯可正常運作之後，當函數在 CloudFront 中執行時，仍然可能會出現 HTTP 5xx 錯誤。有各種原因可能傳回 HTTP 5xx 錯誤，包括 Lambda 函數錯誤或 CloudFront 中的其他問題。

  • 如果您使用 Lambda@Edge 函數，您可以使用 CloudFront 主控台中的圖形以協助追蹤造成錯誤的原因，然後試圖修正該錯誤。例如，您可以檢視 HTTP 5xx 錯誤是否由 CloudFront 或 Lambda 函數造成，然後針對特定函數檢視相關的日誌檔案以調查該問題。

  • 若要排除 CloudFront 中的一般性 HTTP 錯誤，請參閱下列主題中的故障診斷步驟：故障診斷 CloudFront 中的錯誤回應狀態碼。

導致 CloudFront 中 Lambda@Edge 函數錯誤的原因

Lambda 函數造成 HTTP 5xx 錯誤的原因有許多種，您應該依據錯誤的類型採取相應的疑難排解步驟。錯誤分類如下：

Lambda 函數執行錯誤

如果因為函數中存在未處理的例外狀況，或程式碼中出現錯誤，而使得 CloudFront 未獲得 Lambda 的回應，會造成執行錯誤。例如，如果程式碼包含回呼 (錯誤)。

無效的 Lambda 函數回應會傳回至 CloudFront

函數執行後，CloudFront 會收到來自 Lambda 的回應。如果回應的物件結構不符合 Lambda@Edge 事件結構說明頁面，或回應中包含無效的標頭或其他無效的欄位，系統會傳回錯誤。

由於 Lambda 服務配額 (以前稱為限制)，CloudFront 中的執行會受到調節

Lambda 服務會在各區域中調節執行作業，並在您超出配額時傳回錯誤。如需詳細資訊，請參閱Lambda@Edge 的配額。

如何判斷故障的類型

為了在您偵錯和解決 CloudFront 傳回的錯誤時協助您決定處理重點，找出為何 CloudFront 會傳回 HTTP 錯誤的原因是很有幫助的。若要開始使用，您可以使用 AWS Management Console上 CloudFront 主控台的 Monitoring (監控) 區段中提供的圖表。如需在 CloudFront 主控台的監控區段檢視圖表的詳細資訊，請參閱使用 Amazon CloudWatch 監控 CloudFront 指標。

以下圖表在您追縱原始伺服器或 Lambda 函數是否傳回錯誤時特別實用，當錯誤是由於 Lambda 函數造成時，也可縮小問題的類型。

錯誤率圖表

在每一個分佈的 Overview (概觀) 標籤上，您可以檢視的其中一個圖表就是 Error rates (錯誤率) 圖表。此圖表顯示錯誤率佔進入您分配的請求總數的百分比。此圖表顯示總錯誤率，總共 4xx 個錯誤、總共 5xx 個錯誤，以及總共 5xx 個 Lambda 函數的錯誤。根據錯誤類型和磁碟區，您可以採取步驟以針對原因進行調查和故障診斷。

CloudFront 分佈的錯誤率圖形

  • 如果您看到 Lambda 錯誤，您可以透過查看該函數傳回的特定錯誤類型，以進一步進行調查。Lambda@Edge 錯誤標籤包含了依類型分類的函數錯誤圖表，可協助您找出特定函數的問題。

  • 如果您看到 CloudFront 錯誤，您可以進行故障排除並解決原始伺服器錯誤或變更您的 CloudFront 組態。如需詳細資訊，請參閱故障診斷 CloudFront 中的錯誤回應狀態碼。

執行錯誤和無效函數回應圖表

Lambda@Edge 錯誤標籤包含針對特定分佈 (依類型) 分類 Lambda@Edge 錯誤的圖表。例如，一個圖形顯示 的所有執行錯誤 AWS 區域。

若要更輕鬆地對問題進行故障診斷，您可以依區域開啟和檢查特定函數的日誌檔案，以尋找特定問題。

依區域檢視特定函數的日誌檔案

  1. 在 Lambda@Edge 錯誤索引標籤的關聯 Lambda@Edge 函數下，選擇函數名稱，然後選擇檢視指標。

  2. 接著，在具有函數名稱的頁面上，在右上角選擇檢視函數日誌，然後選擇區域。

    例如，如果您在美國西部 （奧勒岡） 區域的錯誤圖表中看到問題，請從下拉式清單中選擇該區域。這會開啟 Amazon CloudWatch 主控台。

  3. 在該區域的 CloudWatch 主控台的日誌串流下，選擇日誌串流以檢視函數的事件。

此外，請閱讀此章的下列各節，以了解有關故障排除和修復錯誤的更多建議。

調節圖表

Lambda@Edge 錯誤標籤也包含調節圖表。有時，如果您到達區域並行數量配額 (先前稱為限制)，則 Lambda 服務會依每一區域為基礎調節您的函數呼叫。如果出現超過限制錯誤，表示您的函數已到達 Lambda 服務對「區域」中的執行作業所施加的配額。如需詳細資訊，包括如何請求提高配額，請參閱Lambda@Edge 的配額。

Lambda@Edge 函數執行的調節圖。

如需如何使用此資訊進行 HTTP 錯誤故障診斷的詳細資訊，請參閱在 AWS上針對您的內容交付執行偵錯的四個步驟。

故障診斷無效的 Lambda@Edge 函數回應 （驗證錯誤）

如果您找到的問題是 Lambda 驗證錯誤，表示您的 Lambda 函數將無效的回應傳回給 CloudFront。請依照本段落中的指引，採取步驟來審視您的函數，並確認回應符合 CloudFront 的請求。

CloudFront 會以兩種方式驗證來自 Lambda 函數的回應：

  • Lambda 回應必須符合所請求的物件結構。錯誤的物件結構範例包括：無法剖析的 JSON、遺漏必要的欄位，以及在回應中包含無效的物件。如需更多資訊，請參閱Lambda@Edge 事件結構說明頁面。

  • 回應必須只包含有效的物件值。如果回應中包含有效的物件，但是具有不支援的值，將會發生錯誤。此種情況的範例包括：新增或更新被列入不允許或唯讀的標頭 (請參閱 對邊緣函數的限制)、超過內文大小的上限 (請參閱 Lambda@Edge 錯誤 主題中的對所產生回應的大小限制)，以及無效的字元或值 (請參閱 Lambda@Edge 事件結構說明頁面)。

當 Lambda 傳回無效回應至 CloudFront 時，會將錯誤訊息寫入日誌檔案，而 CloudFront 會在執行 Lambda 函數的區域中推送至 CloudWatch。出現無效的回應時，預設的動作是將日誌檔案傳送到 CloudWatch。不過，如果在函數發布之前，就已建立 Lambda 函數與 CloudFront 的關聯，則可能不會針對您的函數啟用這項預設動作。如需詳細資訊，請參閱本主題稍後的判斷您的帳戶是否推送日誌到 CloudWatch。

CloudFront 會將日誌檔案推送到對應您函數執行所在位置的區域 (在與您的分佈具有關聯的日誌群組中)。日誌群組具有下列格式：/aws/cloudfront/LambdaEdge/DistributionId，其中 DistributionId 是您分佈的 ID。若要判斷您可以在哪個區域中找到 CloudWatch 日誌檔案，請參閱本主題稍後的判斷 Lambda@Edge 區域。

如果錯誤是可重現的，您可以建立新的請求來造成錯誤，然後在失敗的 CloudFront 回應 (X-Amz-Cf-Id 標頭) 中找到該請求的 ID，然後在日誌檔案中找出單一錯誤。日誌檔案記錄所包含的資訊，可協助您找出傳回錯誤的原因，也可以列出對應的 Lambda 請求 ID，來讓您針對單一請求的範圍，分析錯誤的根本原因。

如果錯誤是間歇性出現，您可以利用 CloudFront 存取日誌，針對失敗的請求找出其請求 ID，然後搜尋 CloudWatch Logs，尋找對應的錯誤訊息。如需詳細資訊，請參閱先前的段落判斷故障的類型。

故障診斷 Lambda@Edge 函數執行錯誤

如果問題是 Lambda 的執行錯誤，那麼建立 Lambda 函數的記錄陳述式、將訊息寫入 CloudWatch 日誌檔案 (此日誌檔案會監控您的函數在 CloudFront 中的執行狀況)，然後判斷函數是否如預期運作，這些動作將會有所幫助。接著，您可以在 CloudWatch 日誌檔案中搜尋這些陳述式，來確認您的函數是否正常運作。

注意

即使您未變更您的 Lambda@ Edge 函數，Lambda 函數執行環境的更新仍會對其造成影響，並因而傳回執行錯誤。如需有關測試和遷移至較新版本的資訊，請參閱 Lambda AWS 和 AWS Lambda@Edge 執行環境的近期更新。

判斷 Lambda@Edge 區域

若要檢視您 Lambda@Edge 函數正在接收流量的區域，請在 AWS Management Console上的 CloudFront 主控台檢視函數的指標圖形。系統會顯示每個 AWS 區域的指標。在同一頁面中，您可以選擇一個區域並檢視該區域的日誌檔，以便調查問題。您必須檢閱正確區域中的 CloudWatch 日誌檔案 AWS ，以查看 CloudFront 執行 Lambda 函數時建立的日誌檔案。

如需在 CloudFront 主控台的監控區段檢視圖表的詳細資訊，請參閱使用 Amazon CloudWatch 監控 CloudFront 指標。

判斷您的帳戶是否將日誌推送至 CloudWatch

根據預設，CloudFront 會啟用記錄無效的 Lambda 函式回應，並使用其中一個 Lambda@Edge 的服務連結角色 將日誌檔案推送至 CloudWatch。如果您擁有 Lambda@Edge 函數，而在無效的 Lambda 函數回應日誌函數推出之前，您已經將此 Lambda@Edge 函數新增到 CloudFront，而當您後續更新 Lambda@Edge 組態時，就會啟用記錄函數 (例如，透過新增 CloudFront 觸發條件)。

您可以執行下列的動作，來確認您的帳戶已啟用推送日誌檔案到 CloudWatch 的功能：

  • 檢查日誌是否顯示在 CloudWatch 中 – 請務必查看執行 Lambda@Edge 函數的 區域。如需詳細資訊，請參閱 判斷 Lambda@Edge 區域。

  • 在 IAM 中判斷您的帳戶中是否存在相關的服務連結角色 – 您的帳戶AWSServiceRoleForCloudFrontLogger中必須有 IAM 角色。如需有關此角色的詳細資訊，請參閱 Lambda@Edge 的服務連結角色。