生成自定义错误响应 - Amazon CloudFront
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

生成自定义错误响应

如果您通过 CloudFront 提供的对象出于某种原因不可用,您的 Web 服务器通常会返回相应的 HTTP 状态代码到 CloudFront 来进行指示。例如,如果查看器请求了无效 URL,您的 Web 服务器将向 CloudFront 返回 HTTP 404(未找到)状态代码,然后 CloudFront 会将此状态代码返回至查看器。

如果您愿意,也可以配置 CloudFront 向查看器返回自定义错误响应。此外,对于管理 CloudFront 在出现错误时的响应方式,您有多个选项。要指定自定义错误消息的选项,请更新您的 CloudFront 分配来指定这些值。有关更多信息,请参阅配置错误响应行为

如果您配置 CloudFront 来为 HTTP 状态代码返回自定义错误页面,但自定义错误页面不可用,则 CloudFront 将向查看器返回 CloudFront 从包含自定义错误页面的源接收的状态代码。例如,假设您的自定义源返回 500 状态代码且您已将 CloudFront 配置为从 Amazon S3 存储桶获取 500 状态代码的自定义错误页面。但是,某人意外删除了您存储桶中的自定义错误页面。CloudFront 将 HTTP 404 状态代码(未找到)返回给请求对象的查看器。

当 CloudFront 将自定义错误页面返回至查看器时,您支付的是自定义错误页面的标准 CloudFront 费用,而不是所请求对象的费用。有关 CloudFront 费用的更多信息,请参阅 Amazon CloudFront 定价

配置错误响应行为

要配置自定义错误响应,您可以使用 CloudFront 控制台、CloudFront API 或 Amazon CloudFormation。无论您选择哪种方式来更新配置,请考虑以下提示和建议:

  • 在 CloudFront 可访问的位置保存自定义错误页面。建议您将这些页面存储在 Amazon S3 存储桶中,并且不要将它们与您的网站或应用程序的其余内容存储于同一位置。如果您将自定义错误页面与您的网站或应用程序存储在同一个源上,且源开始返回 5xx 错误,则 CloudFront 无法获取自定义错误页面,因为源服务器不可用。有关更多信息,请参阅将对象和自定义错误页面存储在不同的位置

  • 确保 CloudFront 有权获取自定义错误页面。如果自定义错误页面存储在 Amazon S3 中,则这些页面必须可公开访问,或者您必须配置 CloudFront 源访问控制(OAC)。如果自定义错误页面存储在自定义源中,则这些页面必须可公开访问。

  • (可选)如果您需要,还可以配置您的源,以添加 Cache-ControlExpires 标头以及自定义错误页面。您还可以使用错误缓存最短 TTL 设置来控制 CloudFront 缓存自定义错误页面的时长。有关更多信息,请参阅控制 CloudFront 缓存错误的时间长度

配置自定义错误响应(CloudFront 控制台)

要在 CloudFront 控制台中配置自定义错误响应,您必须具有 CloudFront 分配。在控制台中,自定义错误响应的配置设置仅适用于现有分配。要了解如何创建分配,请参阅 开始使用基本 CloudFront 分配

配置自定义错误响应(控制台)
  1. 登录到Amazon Web Services Management Console并通过以下网址在 CloudFront 控制台 (https://console.amazonaws.cn/cloudfront/v4/home#distributions) 中打开 Distributions (分配) 页面。

  2. 在分配列表里,选择要更新的分配。

  3. 选择错误页面选项卡,然后选择创建自定义错误响应

  4. 输入适用的值。有关更多信息,请参阅自定义错误页面和错误缓存

  5. 输入所需的值后,选择创建

配置自定义错误响应(CloudFront API 或 Amazon CloudFormation)

要通过 CloudFront API 或 Amazon CloudFormation 配置自定义错误响应,您可以使用分配中的 CustomErrorResponse 类型。有关更多信息,请参阅下列内容:

为特定 HTTP 状态代码创建自定义错误页面

如果您希望显示自定义错误消息而不是默认消息 – 例如,使用与网站其他部分相同的格式设置的页面 – 则可以让 CloudFront 向查看器返回包含自定义错误消息的对象(例如,HTML 文件)。

要指定您希望返回的文件以及应为此文件返回的错误,请更新您的 CloudFront 分配以指定这些值。有关更多信息,请参阅配置错误响应行为

例如,以下是一个自定义错误页面:


				Amazon 404 页面

您可以为每个支持的 HTTP 状态代码指定一个不同的对象,也可以对所有支持的状态代码使用同一个对象。您可以选择为一些状态代码指定自定义错误页面,而不为另外一些状态代码指定自定义错误页面。

您通过 CloudFront 提供的对象出于各种原因可能不可用。可将这些原因归为以下两大类:

  • 客户端错误表示请求出现问题。例如,具有指定名称的对象不可用,或用户不具有获取您 Amazon S3 存储桶中的对象所需的权限。当出现客户端错误时,源会向 CloudFront 返回一个 4xx 区间内的 HTTP 状态代码。

  • 服务器错误表示源服务器出现问题。例如,HTTP 服务器繁忙或不可用。当出现服务器错误时,您的源服务器将向 CloudFront 返回一个 5xx 区间内的 HTTP 状态代码,或者在某一时间段内 CloudFront 未从您的源服务器获得响应,此时显示 504 状态代码(网关超时)。

CloudFront 可以为其返回自定义错误页面的 HTTP 状态代码包含以下各项:

  • 400、403、404、405、414、416

    注意
    • 如果 CloudFront 检测到请求可能不安全,CloudFront 将返回 400(错误请求)错误,而不是自定义错误页面。

    • 您可以为 HTTP 状态代码 416(无法满足请求的范围)创建自定义错误页面,并可以更改源向 CloudFront 返回状态代码 416 时 CloudFront 向查看器返回的 HTTP 状态代码。(有关更多信息,请参阅 更改 CloudFront 返回的响应代码。) 但是,CloudFront 不缓存状态代码 416 响应,因此,即使您为状态代码 416 指定 Error Caching Minimum TTL(错误缓存最小 TTL)的值,CloudFront 也不会使用它。

  • 500、501、502、503、504

    注意

    在某些情况下,即使您对 CloudFront 进行配置,使其为 HTTP 503 状态代码返回自定义错误页面,CloudFront 也不会执行此操作。如果 CloudFront 错误代码为 Capacity ExceededLimit Exceeded,CloudFront 会将 503 状态代码(而非自定义错误页面)返回至查看器。

有关 CloudFront 如何处理来自您的源的错误响应的详细说明,请参阅CloudFront 如何处理和缓存来自源的 HTTP 4xx 和 5xx 状态代码

将对象和自定义错误页面存储在不同的位置

如果您希望将您的对象和自定义错误页面存储在不同的位置,您的分配必须包含满足以下条件时的缓存行为:

  • Path Pattern 的值与您的自定义错误消息的路径匹配。例如,假设您在 Amazon S3 存储桶中名为 /4xx-errors 的目录下为 4xx 错误保存了自定义错误页面。您的分配必须包含缓存行为,其路径模式将对自定义错误页面的请求路由至该位置,例如 /4xx-errors/*

  • 值指定包含您的自定义错误页面的源的源 ID 值。

有关更多信息,请参阅缓存行为设置

更改 CloudFront 返回的响应代码

您可以配置 CloudFront 向查看器返回的 HTTP 状态代码,使其与 CloudFront 从源接收的状态代码不相同。例如,如果源向 CloudFront 返回 500 状态代码,您可能希望 CloudFront 向查看器返回自定义错误页面和 200 状态代码 (OK)。出于多种原因,您可能希望 CloudFront 向查看器返回不同于源返回到 CloudFront 的状态代码:

  • 一些互联网设备(例如,一些防火墙和企业代理)会拦截 HTTP 4xx 和 5xx 状态代码,防止响应返回到查看器。在这种情况下,如果您替换 200,就不会截获响应。

  • 如果您不希望区分不同的客户端错误或服务器错误,可以将 CloudFront 为所有 4xx 或 5xx 状态代码返回的值指定为 400500

  • 您可能希望返回 200 状态代码 (OK) 和静态网站,确保客户不知道网站宕机。

如果您启用 CloudFront 标准日志并且将 CloudFront 配置为更改响应中的 HTTP 状态代码,则标准日志中 sc-status 列的值将包含您指定的状态代码。但是,x-edge-result-type 列的值不受影响。该值包含源响应的结果类型。例如,假设您将 CloudFront 配置为在源将 200(未找到)返回到 CloudFront 时将 404 的状态代码返回到查看器。当源使用 404 状态代码响应请求时,日志中 sc-status 列的值将为 200,但 x-edge-result-type 列的值将为 Error

您可以将 CloudFront 配置为随自定义错误页面返回以下任意 HTTP 状态代码:

  • 200

  • 400、403、404、405、414、416

  • 500、501、502、503、504

控制 CloudFront 缓存错误的时间长度

CloudFront 缓存错误响应的默认持续时间为 10 秒。CloudFront 然后将对象的下一个请求提交给您的源,以查看导致错误的问题是否已解决,并且请求的对象是否可用。

您可以为 CloudFront 缓存的各 4xx 和 5xx 状态代码指定错误缓存时长(错误缓存最小 TTL)。(有关更多信息,请参阅 CloudFront 缓存的 HTTP 4xx 和 5xx 状态代码。) 指定持续时间时,注意以下几点:

  • 如果您指定一个很短的错误缓存时长,则与指定较长的时长相比,CloudFront 将向您的源转发更多请求。对于 5xx 错误,这可能会加重原先导致源返回错误的问题。

  • 当源针对某个对象返回错误时,CloudFront 会通过错误响应或自定义错误页面响应对象请求,直到超过错误缓存时间长度。如果您指定一个很长的错误缓存持续时间,CloudFront 可能会在对象再次转为可用后的很长一段时间内继续使用错误响应或您的自定义错误页面来响应请求。

注意

您可以为 HTTP 状态代码 416(无法满足请求的范围)创建自定义错误页面,并可以更改源向 CloudFront 返回状态代码 416 时 CloudFront 向查看器返回的 HTTP 状态代码。(有关更多信息,请参阅 更改 CloudFront 返回的响应代码。) 但是,CloudFront 不缓存状态代码 416 响应,因此,即使您为状态代码 416 指定 Error Caching Minimum TTL(错误缓存最小 TTL)的值,CloudFront 也不会使用它。

如果您要控制 CloudFront 为各个对象缓存错误的时间长度,可以配置源服务器以为该对象的错误响应添加相应标头。

如果源添加 Cache-Control: max-ageCache-Control: s-maxage 指令或 Expires 标头,则 CloudFront 缓存错误响应的时间为标头中的值或 Error Caching Minimum TTL(错误缓存最小 TTL)值(以较大的值为准)。

注意

Cache-Control: max-ageCache-Control: s-maxage 值不能大于为提取错误页面的缓存行为设置的 Maximum TTL(最大 TTL)值。

如果源添加其他 Cache-Control 指令或不添加标头,则 CloudFront 缓存错误响应的时间等于 Error Caching Minimum TTL(错误缓存最小 TTL)的值。

如果某一对象的 4xx 或 5xx 状态代码的过期时间超过您希望等待的时间且对象再次可访问,您可以使用所请求对象的 URL 使缓存错误代码失效。如果源返回针对多个对象的错误响应,您需要分别使各个对象失效。有关使对象失效的更多信息,请参阅 使文件失效