测试和调试 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 函数与您的分配关联，您必须更改区域以查看伦敦 AWS 区域的 CloudWatch 指标或日志文件。有关更多信息，请参阅 确定 Lambda@Edge 区域。

测试 Lambda@Edge 函数

可以使用两个步骤测试 Lambda 函数：单独测试和集成测试。

测试单独功能

在将 Lambda 函数添加到 CloudFront 之前，请确保先使用 Lambda 控制台中的测试功能或其他方法测试该功能。有关在 Lambda 控制台中进行测试的更多信息，请参阅《AWS Lambda 开发人员指南》中的使用控制台调用 Lambda 函数。

在 CloudFront 中测试您的函数的运行情况

请务必完成集成测试，其中，您的函数与一个分配关联并根据 CloudFront 事件运行。确保为正确的事件触发函数，并为 CloudFront 返回有效且正确的响应。例如，确保事件结构正确无误，仅包含有效标头等等。

在 Lambda 控制台上重复对函数进行集成测试时，请在修改代码或更改调用函数的 CloudFront 触发器时参阅 Lambda@Edge 教程中的步骤。例如，确保您使用带编号的函数版本，如本教程中的以下步骤所述：第 4 步：添加 CloudFront 触发器来运行函数。

在进行更改和部署时，请注意需要几分钟的时间以在所有区域中复制更新的函数和 CloudFront 触发器。这通常需要几分钟，但最长需要 15 分钟。

您可以转到 CloudFront 控制台并查看您的分配，确认复制是否完成。

检查您的复制是否已完成部署

  1. 通过 https://console.aws.amazon.com/cloudfront/v4/home 打开 CloudFront 控制台

  2. 选择分配名称。

  3. 查看分配的状态是否已从正在进行恢复为已部署，这意味着已复制函数。然后，按照下一节中的步骤验证函数是否正常工作。

请注意，控制台中的测试只会验证函数的逻辑，而不会应用特定于 Lambda@Edge 的任何服务限额（以前称为限制）。

识别 CloudFront 中的 Lambda@Edge 函数错误

在确认您的函数逻辑正常工作后，在 CloudFront 中运行函数时，您可能仍会看到 HTTP 5xx 错误。可能返回 HTTP 5xx 错误的原因有很多，其中包括 Lambda 函数错误或 CloudFront 中的其他问题。

  • 如果您使用 Lambda@Edge 函数，则可以在 CloudFront 控制台中使用图表帮助跟踪导致错误的原因，然后进行修复。例如，您可以查看是 CloudFront 还是 Lambda 函数导致了 HTTP 5xx 错误，然后，对于特定函数，您可以查看相关的日志文件来调查问题。

  • 要对 CloudFront 中的常规 HTTP 错误进行问题排查，请参阅以下主题中的问题排查步骤：对 CloudFront 中的错误响应状态代码进行故障排除。

是什么原因导致 CloudFront 中的 Lambda@Edge 函数错误

Lambda 函数导致 HTTP 5xx 错误可能有很多原因，您应采取的故障排除措施取决于错误类型。错误可以归类如下：

Lambda 函数执行错误。

如果由于函数中存在未处理的异常或代码中存在错误，使得 CloudFront 没有从 Lambda 中收到响应，则会导致执行错误。例如，如果代码包含回调（错误）。

向 CloudFront 返回无效的 Lambda 函数响应

函数运行后，CloudFront 会收到来自 Lambda 的响应。如果响应的对象结构不符合 Lambda@Edge 事件结构，或响应包含无效的标头或其他无效的字段，则会返回错误。

由于 Lambda 服务配额（以前称为限制），CloudFront 中的执行受到限制

Lambda 服务限制每个区域中的执行次数，并在超过配额时返回错误。有关更多信息，请参阅 有关 Lambda@Edge 的配额。

如何确定故障类型

为了帮助您在调试和处理以解决 CloudFront 返回的错误时确定重点，确定 CloudFront 返回 HTTP 错误的原因会有所帮助。要开始使用，您可以使用 AWS Management Console 上 CloudFront 控制台的监控部分中提供的图表。有关在 CloudFront 控制台的监控部分中查看图表的更多信息，请参阅使用 Amazon CloudWatch 监控 CloudFront 指标。

在您希望跟踪错误是由源还是由 Lambda 函数返回时，以及在错误源自 Lambda 函数时需要缩小问题类型的范围时，下列图表会非常有用。

错误率图表

在概览选项卡上，您可以看到各个分配的一个图表是错误率图表。此图表显示相对于传入到您分配的请求总数，错误率的百分比。图表显示总错误率、4xx 错误总数、5xx 错误总数以及来自 Lambda 函数的 5xx 错误总数。根据错误类型和卷，您可以采取措施来调查和排查造成错误的原因。

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 错误 主题中的生成的响应大小的限制）和无效的字符或值（请参阅 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 日志中搜索相应的错误消息。有关更多信息，请参阅上一节确定故障类型。

排查 Lambda@Edge 函数执行错误

如果问题是 Lambda 执行错误，为 Lambda 函数创建日志记录语句以将消息写入到 CloudWatch 日志文件可能是非常有用的，从而在 CloudFront 中监视函数的执行情况并确定它是否正常工作。然后，您可以在 CloudWatch 日志文件中搜索这些语句，以验证您的函数是否正常工作。

注意

即使您尚未更改 Lambda@Edge 函数，对该 Lambda 函数执行环境的更新也可能会影响它并可能返回执行错误。有关测试和迁移到更高版本的信息，请参阅对 AWS Lambda 和 AWS Lambda@Edge 执行环境的近期更新。

确定 Lambda@Edge 区域

要查看 Lambda@Edge 函数接收流量的区域，请在 AWS Management Console上的 CloudFront 控制台中查看此函数的指标。指标针对各个 AWS 区域显示。在同一页上，您可以选择一个区域并查看该区域的日志文件，从而调查问题。您必须查看相应 AWS 区域中的 CloudWatch 日志文件，以查看在 CloudFront 执行 Lambda 函数时创建的日志文件。

有关在 CloudFront 控制台的监控部分中查看图表的更多信息，请参阅使用 Amazon CloudWatch 监控 CloudFront 指标。

确定您的账户是否将日志推送到 CloudWatch

默认情况下，CloudFront 为无效的 Lambda 函数响应启用日志记录，并使用Lambda@Edge 的服务相关角色之一将日志文件推送到 CloudWatch。如果在发布无效的 Lambda 函数响应日志功能之前将 Lambda@Edge 函数添加到 CloudFront，下次更新 Lambda@Edge 配置时，将启用日志记录，例如，通过添加 CloudFront 触发器。

您可以执行以下操作，以验证是否为您的账户启用将日志文件推送到 CloudWatch 的功能：

  • 检查日志是否显示在 CloudWatch 中 – 确保您查看了执行 Lambda@Edge 函数的区域。有关更多信息，请参阅 确定 Lambda@Edge 区域。

  • 在 IAM 中确定您的账户中是否存在相关的服务相关角色 – 您的账户中必须有 IAM 角色 AWSServiceRoleForCloudFrontLogger。有关该角色的更多信息，请参阅 Lambda@Edge 的服务相关角色。