本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # Amplify 对 Next.js 的支持 Amplify 支持部署和托管使用 Next.js 创建的服务器端渲染（SSR）Web 应用程序。Next.js 是一个用于开发 SPAs 的 React 框架 JavaScript。您可以部署使用 Next.js 15 及更低版本的 Next.js 构建，且具有映像优化和中间件等功能的应用程序。 开发人员可以使用 Next.js 将静态网站生成 (SSG) 和 SSR 融合到一个项目中。SSG 页面在构建时预渲染，SSR 页面在请求时预渲染。 预渲染可以增强性能和搜索引擎优化。由于 Next.js 会预渲染服务器上的所有页面，因此每个页面的 HTML 内容在到达客户端的浏览器时就已准备就绪。这一内容的加载速度也更快。加载速度加快可以改善最终用户的网站体验，对网站的 SEO 排名产生积极影响。预渲染还使搜索引擎机器人能够轻松查找和爬取网站的 HTML 内容，从而改进 SEO。 Next.js 为衡量各种性能指标提供了内置的分析支持，例如首字节时间 (TTFB) 和首次内容绘制 (FCP)。有关 Next.js 的更多信息，请参阅 Next.js 网站上的[开始使用](https://nextjs.org/docs/getting-started)。 ## Next.js 功能支持 对于使用 Next.js 版本 12 至 15 构建的应用程序，服务器端渲染（SSR）完全由 Amplify Hosting 计算管理。 如果您在 2022 年 11 月发布 Amplify Hosting 计算功能之前在 Amplify 上部署了 Next.js 应用程序，则该应用程序使用的是 Amplify 之前的 SSR 提供程序 Classic（仅限 Next.js 11）。Amplify Hosting 计算不支持使用 Next.js 11 或更早版本创建的应用程序。我们强烈建议您将 Next.js 11 应用程序迁移至 Amplify Hosting 计算托管 SSR 提供商。 以下列表描述了 Amplify Hosting 计算 SSR 提供商支持的具体功能。 **支持的特征** + 服务器端渲染的页面 (SSR) + 静态页面 + API 路由 + 动态路由 + 捕获所有路由 + 静态生成 (SSG) + 增量静态再生成 (ISR) + 国际化 (i18n) 子路径路由 + 国际化 (i18n) 域名路由 + 国际化 (i18n) 自动区域检测 + 中间件 + 环境变量 + 图像优化 + Next.js 13 应用程序目录 **不支持的功能** + 边缘 API 路由（*不支持边缘中间件*） + *按需*增量静态再生成 (ISR) + Next.js 流式处理 + 基于静态资产和经优化的图像运行中间件 + 收到 `unstable_after` 响应后执行代码（Next.js 15 中发布的实验性功能） ### Next.js 图像 最大图像输出大小不能超过 4.3 MB。您可以将更大的图像文件存储在某个地方，然后使用 Next.js Image 组件调整尺寸并将其优化为 Webp 或 AVIF 格式，再以较小的尺寸提供。 注意，Next.js 文档建议您安装 Sharp 图像处理模块，使图像优化能够在生产环境中正常运行。但是，Amplify 部署不需要如此。Amplify 会自动为您部署 Sharp。 # 将 Next.js SSR 应用程序部署到 Amplify 默认情况下，Amplify 使用 Amplify Hosting 的计算服务（支持 Next.js 版本 12 至 15）来部署新 SSR 应用程序。Amplify Hosting 计算可完全管理部署 SSR 应用程序所需的资源。您的 Amplify 账户中在 2022 年 11 月 17 日之前部署的 SSR 应用程序使用的是 Classic（仅限 Next.js 11）SSR 提供商。 我们强烈建议您将使用 Classic（仅限 Next.js 11）SSR 的应用程序迁移至 Amplify Hosting 计算 SSR 提供商。Amplify 不会自动为您执行迁移。您必须手动迁移应用程序，然后启动新版本完成更新。有关说明，请参阅[将 Next.js 11 SSR 应用程序迁移至 Amplify Hosting 计算](update-app-nextjs-version.md)。 请按照以下说明操作以部署新的 Next.js SSR 应用程序。 **使用 Amplify Hosting 计算 SSR 提供商将 SSR 应用程序部署到 Amplify** 1. 登录 AWS 管理控制台 并打开 [Amplify](https://console.aws.amazon.com/amplify/) 控制台。 1. 在**所有应用程序**页面中，选择**创建新应用程序**。 1. 在**开始使用 Amplify 进行构建**页面中选择您的 Git 存储库提供商，然后选择**下一步**。 1. 在**添加存储库分支**页面上，执行以下操作： 1. 在**最近更新的存储库**列表中，选择要连接的存储库的名称。 1. 在**分支**列表中，选择要连接的存储库分支的名称。 1. 选择**下一步**。 1. 该应用程序需要一个 IAM 服务角色，Amplify 在代表您调用其他服务时会代入该角色。您可以允许 Amplify Hosting 计算自动为您创建服务角色，也可以指定您已创建的角色。 + 允许 Amplify 自动创建角色并将其附加到您的应用程序的方法： 1. 请选择**创建和使用新的服务角色**。 + 附加您之前创建的服务角色的方法： 1. 选择**使用现有服务角色**。 1. 从列表中选择需要使用的角色。 1. 选择**下一步**。 1. 在**查看**页面上，选择**保存并部署**。 ## Package.json 文件设置 部署 Next.js 应用程序时，Amplify 会在 `package.json` 文件中检查该应用程序的构建脚本，以确定应用程序类型。 以下是适用于 Next.js 应用程序的构建脚本示例。构建脚本 `"next build"` 表示该应用程序同时支持 SSG 和 SSR 页面。此构建脚本也用于仅使用 Next.js 14 或更高版本的 SSG 应用程序。 ``` "scripts": { "dev": "next dev", "build": "next build", "start": "next start" }, ``` 以下是适用于 Next.js 13 或之前版本的 SSG 应用程序的构建脚本示例。构建脚本 `"next build && next export"` 表明该应用程序仅支持 SSG 页面。 ``` "scripts": { "dev": "next dev", "build": "next build && next export", "start": "next start" }, ``` ## Amplify Next.js SSR 应用程序的构建设置 在检查应用程序的 `package.json` 文件后，Amplify 会检查该应用程序的构建设置。您可以将构建设置保存在 Amplify 控制台中，也可以保存在存储库根目录下的 `amplify.yml` 文件中。有关更多信息，请参阅 [配置 Amplify 应用程序的构建设置](build-settings.md)。 如果 Amplify 检测到您部署的是 Next.js SSR 应用程序，但不存在任何 `amplify.yml` 文件，则它会为该应用程序生成构建规范并将 `baseDirectory` 设置为 `.next`。如果您部署的是存在 `amplify.yml` 文件的应用程序，则该文件中的构建设置会覆盖控制台中的所有构建设置。因此，您必须在文件中将 `baseDirectory` 手动设置为 `.next`。 以下是将 `baseDirectory` 设置为 `.next` 的应用程序的构建设置示例。这表明构建构件适用于支持 SSG 和 SSR 页面的 Next.js 应用程序。 ``` version: 1 frontend: phases: preBuild: commands: - npm ci build: commands: - npm run build artifacts: baseDirectory: .next files: - '**/*' cache: paths: - node_modules/**/* ``` ## 适用于 Next.js 13 或之前版本的 SSG 应用程序的 Amplify 构建设置 如果 Amplify 检测到您在部署 Next.js 13 或之前版本的 SSG 应用程序，则会为该应用程序生成构建规范并将 `baseDirectory` 设置为 `out`。如果您部署的是存在 `amplify.yml` 文件的应用程序，则必须在文件中将 `baseDirectory` 手动设置为 `out`。`out` 目录是 Next.js 为存储导出的静态资源而创建的默认文件夹。配置应用程序的编译规范设置时，请更改 `baseDirectory` 文件夹的名称，以匹配您的应用程序配置。 以下是应用程序构建设置的示例，其中 `baseDirectory` 设置为 `out`，指明该构建构件适用于仅支持 SSG 页面的 Next.js 13 或之前版本的应用程序。 ``` version: 1 frontend: phases: preBuild: commands: - npm ci build: commands: - npm run build artifacts: baseDirectory: out files: - '**/*' cache: paths: - node_modules/**/* ``` ## Next.js 14 或更高版本 SSG 应用程序的 Amplify 构建设置 在 Next.js 14 版本中，`next export` 命令已被弃用，并替换为 `next.config.js` 文件中的 `output: 'export'`，以启用静态导出。如果您在控制台部署仅限 Next.js 14 SSG 的应用程序，Amplify 会为该应用程序生成规范并将 `baseDirectory` 设置为 `.next`。如果您部署的是存在 `amplify.yml` 文件的应用程序，则必须在文件中将 `baseDirectory` 手动设置为 `.next`。这与 Amplify 为同时支持 SSG 和 SSR 页面的 Next.js `WEB_COMPUTE` 应用程序使用的 `baseDirectory` 设置相同。 以下是适用于仅限 Next.js 14 SSG 的应用程序构建设置的示例，其中的 `baseDirectory`设置为 `.next`。 ``` version: 1 frontend: phases: preBuild: commands: - npm ci build: commands: - npm run build artifacts: baseDirectory: .next files: - '**/*' cache: paths: - node_modules/**/* ``` # 将 Next.js 11 SSR 应用程序迁移至 Amplify Hosting 计算 部署新的 Next.js 应用程序时，默认情况下 Amplify 使用支持的 Next.js 最新版本。目前，Amplify Hosting 计算 SSR 提供商支持 Next.js 版本 15。 Amplify 控制台会检测您账户中在 2022 年 11 月发布 Amplify Hosting 计算服务（全面支持 Next.js 版本 12 至 15）之前部署的应用程序。控制台会显示一个信息横幅，标识使用 Amplify 以前的 SSR 提供商 Classic（仅限 Next.js 11）部署的带有分支的应用程序。我们强烈建议您将应用程序迁移至 Amplify Hosting 计算 SSR 提供商。 如果要将托管的 Next.js 11 应用程序更新到 Next.js 12 或更高版本，则在触发部署时可能会出现 `"target" property is no longer supported` 错误。在这种情况下，您必须迁移到 Amplify Hosting 计算服务。 您必须同时手动迁移应用程序及其所有生产分支。应用程序不能同时包含 Classic（仅限 Next.js 11）和 Next.js 12 或更新版本的分支。 按照以下说明将应用程序迁移至 Amplify Hosting 计算 SSR 提供商。 **将应用程序迁移至 Amplify Hosting 计算 SSR 提供商** 1. 登录 AWS 管理控制台 并打开 [Amplify](https://console.aws.amazon.com/amplify/) 控制台。 1. 选择要迁移的 Next.js 应用程序。 **注意** 在 Amplify 控制台中迁移应用程序之前，必须先将应用程序的 package.json 文件更新，以使用 Next.js 12 或更高版本。 1. 在导航窗格中，依次选择**应用程序设置**、**常规**。 1. 如果应用程序有通过 *Classic（仅限 Next.js 11）***SSR 提供商**部署的分支，则控制台会在应用程序主页上显示横幅。在横幅上，选择**迁移**。 1. 在迁移确认窗口中，选择三条语句并选择**迁移**。 1. Amplify 将构建并重新部署您的应用程序以完成迁移。 ## 恢复 SSR 迁移 当您部署 Next.js 应用程序时，Amplify Hosting 会检测应用程序中的设置并为该应用程序设置内部平台值。有三个有效平台值。SSG 应用程序设置为平台值 `WEB`。使用 Next.js 版本 11 的 SSR 应用程序设置为平台值 `WEB_DYNAMIC`。Next.js 12 或更高版本的 SSR 应用程序设置为平台值 `WEB_COMPUTE`。 当您按照上一节中的说明迁移应用程序时，Amplify 会将应用程序的平台值从 `WEB_DYNAMIC` 更改为 `WEB_COMPUTE`。向 Amplify Hosting 计算完成迁移后，您无法在控制台中恢复迁移。要恢复迁移，必须使用 AWS Command Line Interface 将应用程序的平台值改回 `WEB_DYNAMIC`。打开终端窗口并输入以下命令，使用您的唯一信息更新应用程序 ID 和区域。 ``` aws amplify update-app --app-id abcd1234 --platform WEB_DYNAMIC --region us-west-2 ``` # 为静态 Next.js 应用程序添加 SSR 功能 您可以向部署有 Amplify 的现有静态 (SSG) Next.js 应用程序添加 SSR 功能。在开始将 SSG 应用程序转换为 SSR 之前，请将应用程序更新为使用 Next.js 12 或更高版本，并添加 SSR 功能。然后，您需要执行以下步骤。 1. 使用 AWS Command Line Interface 更改应用程序的平台类型。 1. 向应用程序添加服务角色。 1. 更新应用程序构建设置中的输出目录。 1. 更新应用程序的 `package.json` 文件以表明该应用程序使用 SSR。 ## 更新平台 有三个平台类型的有效值。SSG 应用程序设置为平台类型 `WEB`。使用 Next.js 版本 11 的 SSR 应用程序设置为平台类型 `WEB_DYNAMIC`。对于借助由 Amplify Hosting 计算托管的 SSR 部署到 Next.js 12 或更新版本的应用程序，平台类型设置为 `WEB_COMPUTE`。 当您将应用程序部署为 SSG 应用时，Amplify 会将平台类型设置为 `WEB`。使用 AWS CLI 将您的应用程序的平台更改为`WEB_COMPUTE`。打开终端窗口，输入以下命令，使用您的应用程序 ID 和区域更新红色文本。 ``` aws amplify update-app --app-id abcd1234 --platform WEB_COMPUTE --region us-west-2 ``` ## 添加服务角色 服务角色是 Amplify 在代表您调用其他服务时扮演的 AWS Identity and Access Management (IAM) 角色。按照以下步骤向已部署 Amplify 的 SSG 应用程序添加服务角色。 **添加服务角色** 1. 登录 AWS 管理控制台 并打开 [Amplify](https://console.aws.amazon.com/amplify/) 控制台。 1. 如果您尚未在 Amplify 账户中创建服务角色，请参阅[添加服务角色](amplify-service-role.md)以完成此先决条件。 1. 选择要向其添加服务角色的静态 Next.js 应用程序。 1. 在导航窗格中，依次选择**应用程序设置**、**常规**。 1. 在**详情**页上，选择**编辑** 1. 对于**服务角色**，请选择现有服务角色的名称或您在步骤 2 中创建的服务角色的名称。 1. 选择**保存**。 ## 更新构建设置 在重新部署具有 SSR 功能的应用程序之前，必须更新应用程序的构建设置，将输出目录设置为 `.next`。您可以在 Amplify 控制台或存储库中存储的 `amplify.yml` 文件中编辑构建设置。有关更多信息，请参阅 [配置 Amplify 应用程序的构建设置](build-settings.md)。 以下是将 `baseDirectory` 设置为 `.next` 的应用程序的构建设置示例。 ``` version: 1 frontend: phases: preBuild: commands: - npm ci build: commands: - npm run build artifacts: baseDirectory: .next files: - '**/*' cache: paths: - node_modules/**/* ``` ## 更新 package.json 文件 添加服务角色并更新构建设置后，更新应用程序的 `package.json` 文件。如下例所示，将构建脚本设置为 `"next build"`，以指示 Next.js 应用程序同时支持 SSG 和 SSR 页面。 ``` "scripts": { "dev": "next dev", "build": "next build", "start": "next start" }, ``` Amplify 会检测存储库中 `package.json` 文件的更改，并重新部署具有 SSR 功能的应用程序。 # 令服务器端运行时可以访问环境变量 Amplify Hosting 支持在 Amplify 控制台的项目配置中设置环境变量，从而为应用程序的构建添加环境变量。 但是，默认情况下，Next.js 服务器组件无权访问这些环境变量。此行为意在保护您的应用程序在构建阶段使用的环境变量所存储的任何密钥。 要使 Next.js 可以访问特定的环境变量，您可以修改 Amplify 构建规范文件，在 Next.js 可识别的环境文件中设置环境变量。这样 Amplify 就能够在构建应用程序之前加载这些环境变量。 **重要** 我们强烈建议您不要在环境变量中存储任何凭证、机密或敏感信息，因为任何有权访问部署构件的用户都可以读取这些信息。 要授予您的 SSR 计算函数访问 AWS 资源的权限，我们建议[使用 IAM 角色](amplify-SSR-compute-role.md)。 以下构建规范示例演示了如何在构建命令部分中添加环境变量。 ``` version: 1 frontend: phases: preBuild: commands: - npm ci build: commands: - env | grep -e API_BASE_URL >> .env.production - env | grep -e NEXT_PUBLIC_ >> .env.production - npm run build artifacts: baseDirectory: .next files: - '**/*' cache: paths: - node_modules/**/* - .next/cache/**/* ``` 在此示例中，构建命令部分包含两个在应用程序的构建运行之前将环境变量写入 `.env.production` 文件的命令。Amplify Hosting 允许您的应用程序在接收流量时访问这些变量。 上例中，构建命令部分的下一行演示了如何从构建环境中获取特定变量，并将其添加到 `.env.production` 文件中。 ``` - env | grep -e API_BASE_URL -e APP_ENV >> .env.production ``` 如果您的构建环境中存在这些变量，则 `.env.production` 文件将包含以下环境变量。 ``` API_BASE_URL=localhost APP_ENV=dev ``` 上例中，构建命令部分的下一行演示了如何向 `.env.production` 文件中添加带有特定前缀的环境变量。此示例中添加的变量都带有前缀 `NEXT_PUBLIC_`。 ``` - env | grep -e NEXT_PUBLIC_ >> .env.production ``` 如果构建环境中存在多个带有 `NEXT_PUBLIC_` 前缀的变量，则 `.env.production` 文件将如下所示。 ``` NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk NEXT_PUBLIC_GRAPHQL_ENDPOINT=uowelalsmlsadf NEXT_PUBLIC_FEATURE_FLAG=true ``` ## 适用于 monorepos 的 SSR 环境变量 如果您在 monorepo 中部署 SSR 应用程序，并希望使特定环境变量可供 Next.js 访问，则必须使用应用程序根目录作为 `.env.production` 文件的前缀。以下适用于 Next.js 的构建规范示例位于一个 Nx monorepo 中，演示了如何在构建命令部分中添加环境变量。 ``` version: 1 applications: - frontend: phases: preBuild: commands: - npm ci build: commands: - env | grep -e API_BASE_URL -e APP_ENV >> apps/app/.env.production - env | grep -e NEXT_PUBLIC_ >> apps/app/.env.production - npx nx build app artifacts: baseDirectory: dist/apps/app/.next files: - '**/*' cache: paths: - node_modules/**/* buildPath: / appRoot: apps/app ``` 上例中，构建命令部分的后续行演示了如何从构建环境中获取特定变量，并针对应用程序根目录为 `apps/app` 的 monorepo 中的应用程序将其添加到 `.env.production` 文件中。 ``` - env | grep -e API_BASE_URL -e APP_ENV >> apps/app/.env.production - env | grep -e NEXT_PUBLIC_ >> apps/app/.env.production ``` # 在单一存储库中部署 Next.js 应用程序 Amplify 支持通用单一存储库中的应用程序，以及使用 npm 工作空间、pnpm 工作空间、Yarn 工作空间、Nx 和 Turborepo 创建的单一存储库中的应用程序。当您部署应用程序时，Amplify 会自动检测您所使用的单一存储库构建框架。Amplify 会自动为 npm 工作空间、Yarn 工作空间或 Nx 中的应用程序应用构建设置。Turborepo 和 pnpm 应用程序需要额外的配置。有关更多信息，请参阅 [配置 monorepo 构建设置](monorepo-configuration.md)。 有关 Nx 的详细示例，请参阅[在 AWS Amplify Hosting 上使用 Nx 在 Next.js 应用程序之间共享代码](https://aws.amazon.com/blogs/mobile/share-code-between-next-js-apps-with-nx-on-aws-amplify-hosting/)博客文章。