Amplify Hosting 问题排查 - AWS Amplify 托管
HTTP 429 状态码（请求过多）Amplify 控制台未显示我应用程序的构建状态和上次更新时间未为新拉取请求创建 Web 预览我的手动部署在 Amplify 控制台中停滞在待处理状态我需要更新我应用程序的 Node.js 版本

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

Amplify Hosting 问题排查

以下信息可帮助您解决与 Amplify Hosting 相关的一般性问题。

HTTP 429 状态码（请求过多）

Amplify 会根据传入请求耗费的处理时间和数据传输量来控制向您的网站发送的每秒请求数（RPS）。如果您的应用程序返回 HTTP 429 状态码，则传入请求将超过为您的应用程序分配的处理时间和数据传输量。此应用程序限制由 Amplify 的 REQUEST_TOKENS_PER_SECOND 服务配额管理。有关限额的更多信息，请参阅Amplify 托管服务限额。

如果修复此问题，我们建议您优化应用程序以缩短请求持续时间、降低数据传输量，以提高应用程序的 RPS。例如，在同样使用 20,000 个词元的情况下，与延迟超过 200 毫秒的页面相比，在 100 毫秒内响应且高度优化的 SSR 页面可支持更高的 RPS。

同样，返回大小为 1 MB 的响应的应用程序将比返回 250 KB 响应大小的应用程序消耗更多的词元数。

我们还建议您通过配置Cache-Control标头来利用 Amazon CloudFront 缓存，以最大限度地延长给定响应在缓存中的保留时间。从 CloudFront 缓存中处理的请求不计入速率限制。每个 CloudFront 分发每秒最多可处理 250,000 个请求，使您能够使用缓存将应用程序扩展得非常高。有关 CloudFront 缓存的更多信息，请参阅 Amazon CloudFront 开发者指南中的优化缓存和可用性。

Amplify 控制台未显示我应用程序的构建状态和上次更新时间

当您在 Amplify 控制台中导航到所有应用程序页面时，系统会为当前区域中的每个应用程序显示一个磁贴。如果您看不到应用程序的构建状态（例如已部署）和上次更新时间，则表示该应用程序没有关联的 Production 暂存区分支。

Amplify 使用 ListApps API 在控制台中列出应用程序。Amplify 使用 ProductionBranch.status 属性来显示构建状态，并使用 ProductionBranch.lastDeployTime 属性来显示上次更新时间。有关此 API 的更多信息，请参阅 Amplify Hosting API 文档ProductionBranch中的。

按照以下说明将 Production 暂存区关联到您应用程序的分支。

  1. 登录 Amplify 控制台。

  2. 在所有应用程序页面上，选择要更新的应用程序。

  3. 在导航窗格中，依次选择应用程序设置和分支设置。

  4. 在分支设置部分中，选择编辑。

  5. 在生产分支中，选择要使用的分支名称。

  6. 选择保存。

  7. 返回所有应用程序页面。现在应该会显示您应用程序的构建状态和上次更新时间。

未为新拉取请求创建 Web 预览

借助 Web 预览功能，您可以在将拉取请求合并到集成分支之前预览拉取请求将执行的更改。对于向存储库发出的每个拉取请求，Web 预览会将其部署到一个与主网站所用 URL 不同的唯一预览 URL。

如果您已为应用程序开启网络预览，但不是为新应用程序创建的 PRs，请调查以下原因是否是导致问题的原因。

  1. 检查您的应用程序是否已达到最大 Branches per app 服务配额。有关限额的更多信息，请参阅Amplify 托管服务限额。

    为遵循每个应用程序 50 个分支的默认配额，可考虑在应用程序中启用自动分支删除。这可以防止在您的账户中累积存储库中已不存在的分支。

  2. 如果您使用的是公共 GitHub 仓库，并且您的 Amplify 应用程序附加了 IAM 服务角色，那么出于安全考虑，Amplify 不会创建预览。例如，带有后端的应用程序和部署到 WEB_COMPUTE 托管平台的应用程序需要一个 IAM 服务角色。因此，如果这些类型的应用程序存储库是公开的，则无法为其启用 Web 预览。

    要使网页预览适用于您的应用程序，您可以取消关联服务角色（如果应用程序没有后端或不是WEB_COMPUTE应用程序），也可以将 GitHub 存储库设为私有。

我的手动部署在 Amplify 控制台中停滞在待处理状态

通过手动部署，您可以在不连接 Git 提供商的情况下，用 Amplify Hosting 发布您的 Web 应用程序。您可以使用以下四种部署选项之一。

  1. 将您的应用程序文件夹拖放到 Amplify 控制台中。

  2. 将包含网站生成构件的 .zip 文件拖放到 Amplify 控制台中。

  3. 将包含网站生成构件的 .zip 文件上传到某个 Amazon S3 存储桶，然后在 Amplify 控制台中将该存储桶连接到某个应用程序。

  4. 在 Amplify 控制台中使用指向包含网站生成构件的 .zip 文件的公有 URL。

我们了解到在 Amplify 控制台中使用应用程序文件夹进行手动部署时，拖放功能存在问题。可能导致这些部署失败的原因如下。

  • 出现暂时性网络问题。

  • 在上传过程中，文件在本地出现更改。

  • 浏览器会话尝试同时上传大量静态资源。

我们正在全力提高拖放上传功能的可靠性。在此期间，我们建议您使用 .zip 文件而不是拖放应用程序文件夹的功能。

我们强烈建议将 .zip 文件上传到 Amazon S3 存储桶，因为这样可以避免从 Amplify 控制台上传文件，并且可以提高手动部署的可靠性。Amplify 与 Amazon S3 的集成简化了这一过程。有关更多信息，请参阅 将 Amazon S3 存储桶中的静态网站部署到 Amplify。

我需要更新我应用程序的 Node.js 版本

对于使用 Node.js 版本 14、16 和 18 的应用程序，Amplify 将于 2025 年 9 月 15 日结束支持。在该日期之后，具体行为将取决于应用程序的类型：

  • SSR 应用程序：使用已弃用的 Node.js 版本时会导致生成失败。在升级到 Node.js 20 或更高版本之前，您将无法部署更新。

  • 非 SSR 应用程序：如果您通过 buildspec 或实时软件包更新手动安装已弃用的 Node.js 版本，则可以继续使用这些版本。

不论是哪个 Node.js 版本，已经部署的应用程序都将继续运行。

如果您使用的是 Amazon Linux 2023 构建映像，则默认支持 Node.js 版本 20。从 2025 年 9 月 15 日起， AL2023 图片将自动支持 Node.js 22，并将其默认 Node.js 版本从 18 更改为 22。

亚马逊 Linux 2 (AL2) 不自动支持 Node.js 版本 20 或更高版本。如果您当前正在使用 AL2，我们建议您切换到 AL2 023。您可以在 Amplify 控制台中更改构建映像，也可以使用支持所指定 Node.js 版本的自定义构建映像。

在升级之前，我们建议您使用新分支来测试您的应用程序，验证其是否能够正常运行。

升级选项

Amplify 控制台

您可以使用 Amplify 控制台中的实时软件包更新功能来指定要使用的 Node.js 版本。有关说明，请参阅在构建映像中使用特定程序包和依赖项版本。

自定义构建映像

如果您使用的是自定义构建镜像，并且映像上安装了 NVM，则可以将 nvm install 20 添加到您的 Dockerfile 中。要详细了解有关自定义构建映像的要求和配置说明，请参阅自定义构建映像。

构建设置

您可以通过将 nvm use 命令添加到 preBuild 命令部分，从而指定要在应用程序的 amplify.yml 构建设置中使用的 Node.js 版本。有关更新应用程序构建设置的说明，请参阅配置 Amplify 应用程序的构建设置。

下例说明了如何自定义构建设置，以在名为 node-20 的测试分支上将默认 Node.js 版本设置为 Node.js 18 并升级到 Node.js 版本 20。

frontend:
  phases:
    preBuild:
      commands:
        - nvm use 18
        - if [ "${AWS_BRANCH}" = "node-20" ]; then nvm use 20; fi
警告

请注意，preBuild 命令会在实时软件包更新完成后运行。nvm use 命令指定的 Node.js 版本将会覆盖由实时软件包更新设置的 Node.js 版本。