NNext.js 中文网 GitHub

如何自托管你的 Next.js 应用程序

了解如何在 Node.js 服务器、Docker 镜像或静态 HTML 文件(静态导出)上自托管你的 Next.js 应用程序。

在部署 Next.js 应用时,你可能需要根据基础设施配置不同功能的处理方式。

🎥 观看: 了解更多关于自托管 Next.js 的内容 → YouTube(45 分钟)。

反向代理#

自托管时,建议在你的 Next.js 服务器前使用反向代理(如 nginx),而不是将其直接暴露在互联网上。反向代理可以处理畸形请求、慢速连接攻击、有效负载大小限制、速率限制以及其他安全问题,将这些任务从 Next.js 服务器卸载。这样服务器就能把资源专用于渲染,而不是请求校验。

图片优化#

使用 next start 部署时,通过 next/image 实现的图片优化无需任何配置即可在自托管环境中工作。如果你希望使用单独的服务来优化图片,可以配置图片加载器。

通过在 next.config.js 中定义自定义图片加载器,静态导出也可以使用图片优化。请注意,图片是在运行时优化的,而不是在构建期间。

小知识:

  • 在基于 glibc 的 Linux 系统上,图片优化可能需要额外配置以防止内存使用过多。
  • 了解更多关于优化后图片的缓存行为以及如何配置 TTL。
  • 如果你愿意,也可以禁用图片优化,同时仍然保留使用 next/image 的其他好处。例如,你自己单独优化图片的情况。

Proxy#

使用 next start 部署时,Proxy 无需任何配置即可在自托管环境中工作。由于它需要访问传入的请求,因此不支持使用静态导出。

如果你想添加需要所有 Node.js API 的逻辑(或使用外部包),或许可以将这些逻辑作为 Server Component 移到 layout 中。例如,检查 headers 和重定向。你也可以使用请求头、cookie 或查询参数,通过 next.config.js 进行重定向或重写。如果这行不通,你还可以使用自定义服务器。

环境变量#

Next.js 可以同时支持构建时和运行时的环境变量。

默认情况下,环境变量仅在服务端可用。要将环境变量暴露给浏览器,必须为其添加 NEXT_PUBLIC_ 前缀。不过,这些公开的环境变量会在 next build 期间被内联到 JavaScript 包中。

要读取运行时环境变量,我们建议使用 getServerSideProps 或增量采用 App Router。

你可以在动态渲染期间安全地在服务端读取环境变量。

app/page.ts
import { connection } from 'next/server'

export default async function Component() {
  await connection()
  // cookies、headers 和其他 Request-time API
  // 也会选择动态渲染,这意味着
  // 此环境变量在运行时被求值
  const value = process.env.MY_VALUE
  // ...
}
app/page.js
import { connection } from 'next/server'

export default async function Component() {
  await connection()
  // cookies、headers 和其他 Request-time API
  // 也会选择动态渲染,这意味着
  // 此环境变量在运行时被求值
  const value = process.env.MY_VALUE
  // ...
}

这使你能够使用单个 Docker 镜像,并在具有不同值的多个环境中推广使用。

小知识:

缓存与 ISR#

Next.js 可以缓存响应、生成的静态页面、构建输出以及其他静态资源,如图片、字体和脚本。

缓存和重新验证页面(使用增量静态再生成(Incremental Static Regeneration))使用的是同一个 Next.js 服务端缓存。默认情况下,该缓存存储在每个 Next.js 服务器实例的本地文件系统(磁盘)上。

对于具有持久化本地磁盘的单个自托管 next start 实例,这一切会自动工作。如果你运行多个实例、使用临时计算资源,或在 Next.js 前面放置 CDN/反向代理,还需查阅配置缓存、多实例缓存协调和与 CDN 配合使用。

如果你想将缓存的页面和数据持久化到持久存储,或在 Next.js 应用程序的多个容器或实例之间共享缓存,可以配置 Next.js 缓存位置。

自动缓存#

  • Next.js 会为真正不可变的资源设置 Cache-Control: public, max-age=31536000, immutable 头。该设置无法被覆盖。这些不可变文件的文件名中包含 SHA 哈希,因此可以安全地无限期缓存。例如静态图片导入。你可以为图片配置 TTL。
  • 增量静态再生成(ISR)会设置 Cache-Control 头为 s-maxage: <revalidate in getStaticProps>, stale-while-revalidate。此重新验证时间以秒为单位在你的 getStaticProps 函数中定义。如果你设置 revalidate: false,则默认缓存时长为一年。要在 CDN 层利用这一点,你的 CDN/反向代理必须遵循这些指令以及缓存键的可变性(CDN 缓存);否则,响应可能会绕过 CDN 缓存,或在客户端导航期间提供过期/不匹配的变体。
  • 动态渲染的页面会设置 Cache-Control: private, no-cache, no-store, max-age=0, must-revalidate 头,以防止用户特定数据被缓存。这同时适用于 App Router 和 Pages Router。这也包括草稿模式(Draft Mode)。

静态资源#

如果你想将静态资源托管在不同的域名或 CDN 上,可以在 next.config.js 中使用 assetPrefix 配置。Next.js 在获取 JavaScript 或 CSS 文件时会使用此资源前缀。将资源分离到不同的域名确实有一个缺点,即会额外花费 DNS 和 TLS 解析时间。

了解更多关于 assetPrefix 的信息。

配置缓存#

默认情况下,生成的缓存资源会存储在内存(默认为 50mb)和磁盘中。在临时计算平台(常见的无服务器配置)上,本地磁盘通常是非持久的或不可用,因此这种缓存实际上是短生命周期且按实例隔离的。如果你使用 Kubernetes 等容器编排平台托管 Next.js,每个 pod 都会有一份缓存副本。由于缓存默认不在 pod 之间共享,为防止显示过期数据,你可以配置 Next.js 缓存,提供一个缓存处理器并禁用内存缓存。

要在自托管时配置缓存位置,请在 next.config.js 文件中设置一个自定义处理器:

next.config.js
module.exports = {
  cacheHandler: require.resolve('./cache-handler.js'),
  cacheMaxMemorySize: 0, // 禁用默认的内存缓存
}

处理器文件导出一个实现了 get、set、revalidateTag 和 resetRequestCache 的类。有关每个方法的签名,请参阅 cacheHandler;有关可运行的实现,请参阅 Redis cacheHandler 示例。

对于生产环境部署,处理器必须:

  • 将条目存储在每个实例都能访问的地方,例如 Redis 或 AWS S3。进程内的存储(例如 Map)会再次让每个 pod 拥有自己的缓存副本。
  • 限制存储大小。 使用 TTL 或基于大小的淘汰策略,移除不再被请求的路径和 fetch 键对应的条目。
  • 序列化条目。 任何进程外的存储都需要这样做。一个条目可能包含 Buffer(例如 rscData)和 Map(例如 segmentData)值,而 JSON.stringify/JSON.parse 无法自行序列化和还原这些值。不处理这种序列化会导致在客户端导航或预取(RSC)请求时出现 segmentData.get is not a function 或 failed to pipe response 之类的错误。
  • 按标签索引条目。 APP_PAGE、APP_ROUTE 和 PAGES 条目在 x-next-cache-tags 响应头(data.headers)中携带其标签,而 ctx.tags 携带 fetch 条目的标签。将索引保存在共享存储中,这样在一个实例上调用 revalidateTag 就会使每个实例上的条目都失效。
  • 处理存储错误,例如超时和连接中断。

小知识:

构建缓存#

Next.js 在 next build 期间生成一个 ID,用于标识正在为你的应用程序提供服务的版本。同一个构建应当被用于并启动多个容器。

如果你要为环境的每个阶段分别重新构建,则需要生成一个一致的构建 ID 供各容器之间使用。在 next.config.js 中使用 generateBuildId 命令:

next.config.js
module.exports = {
  generateBuildId: async () => {
    // 这可以是任何内容,这里使用最新的 git hash
    return process.env.GIT_HASH
  },
}

小知识: 当设置了 deploymentId 后,除非你显式配置 generateBuildId,否则 Next.js 会使用固定的构建 ID。版本偏移(Version skew)会改为从部署 ID 检测。

多服务器部署#

当在多个服务器实例上运行 Next.js 时(例如负载均衡器后面的容器),还需要考虑其他事项以确保行为一致。

Server Functions 加密密钥#

Next.js 会在将 Server Function 闭包变量发送到客户端之前对其进行加密。默认情况下,每次构建都会生成一个唯一的加密密钥。

运行多个服务器实例时,所有实例必须使用相同的加密密钥。否则,由一个实例加密的 Server Function 无法被另一个实例解密,从而导致 "Failed to find Server Action" 错误。

使用 NEXT_SERVER_ACTIONS_ENCRYPTION_KEY 环境变量设置一致的加密密钥。该密钥必须是一个 base64 编码的值,且具有有效的 AES 密钥长度(16、24 或 32 字节)。Next.js 默认生成 32 字节的密钥。

bash
NEXT_SERVER_ACTIONS_ENCRYPTION_KEY=your-generated-key next build

该密钥会嵌入构建输出中,并在运行时自动使用。更多信息请参阅数据安全指南。

部署标识符#

配置 deploymentId 以在滚动部署期间启用版本偏移保护。这确保客户端始终从一致的部署版本接收资源。

共享缓存#

默认情况下,Next.js 使用不会在实例间共享的内存缓存。为了获得一致的缓存行为,请将 'use cache: remote' 与将数据存储在外部存储中的自定义缓存处理器一起使用。

版本偏移(Version Skew)#

在多个实例上自托管或进行滚动部署时,版本偏移(version skew)可能导致:

  • 资源缺失:客户端请求服务器上已不存在的 JavaScript 或 CSS 文件
  • Server Function 不匹配:客户端使用来自先前构建的 ID 调用 Server Function,而服务器已无法识别该 ID
  • 导航失败:来自旧部署的预取页面数据与新服务器不兼容

Next.js 使用 deploymentId 来检测和处理版本偏移。当配置了部署 ID 时:

  • 静态资源包含 ?dpl=<deploymentId> 查询参数
  • 客户端导航请求包含 x-deployment-id 请求头
  • 服务器将客户端的部署 ID 与自身的进行比较

如果检测到不匹配,Next.js 会触发硬导航(整页重新加载),而不是客户端导航。这确保客户端从一致的部署版本获取资源。

next.config.js
module.exports = {
  deploymentId: process.env.DEPLOYMENT_VERSION,
}

小知识: 当应用程序重新加载时,如果应用未设计为在页面导航之间保持状态,则可能会丢失应用状态。URL 状态或本地存储会保留,但像 useState 这样的组件状态会丢失。

不可变资源#

使用不可变静态资源时,防止版本偏移会容易得多:

资源可以在多个部署之间共享,因此只要你持续将它们添加到现有的静态文件文件夹(或 CDN 存储桶)中,就不会出现版本偏移(无需在反向代理中跟踪部署 ID,也无需进行蓝绿部署)。

流式渲染与 Suspense#

自托管时,Next.js App Router 支持流式响应。如果你使用 nginx 或类似的代理,需要将其配置为禁用缓冲以启用流式渲染。

例如,你可以通过将 X-Accel-Buffering 设为 no 来在 nginx 中禁用缓冲:

next.config.js
module.exports = {
  async headers() {
    return [
      {
        source: '/:path*{/}?',
        headers: [
          {
            key: 'X-Accel-Buffering',
            value: 'no',
          },
        ],
      },
    ]
  },
}

除了 nginx,还要确保你的整个基础设施端到端地支持流式渲染:

  • 负载均衡器必须支持分块传输编码或 HTTP/2 流式传输。某些云负载均衡器(例如集成 Lambda 的 AWS ALB)默认可能会缓冲响应。
  • 负载均衡器与 Next.js 之间的反向代理也必须不经过缓冲地传递分块响应。
  • 如果使用部分预渲染(Partial Prerendering),则必须支持流式渲染。否则,静态外壳和动态内容会在完整渲染完成后一起交付,从而失去 PPR 的首字节时间优势。

多实例缓存协调#

除了上面的多服务器配置(加密密钥、部署 ID、共享缓存)之外,具有多个实例的 App Router 部署还需要缓存标签协调。

默认情况下,在一个实例上调用 revalidateTag() 只会使该实例上的缓存失效。其他实例会继续提供过期内容,直到它们自行发现失效。

要在实例之间协调标签失效,请在你的自定义缓存处理器中实现 refreshTags() 方法。此方法会在每个请求之前调用,应从共享存储(如 Redis)同步标签状态,以便所有实例都能及时获知失效。

有关标签架构的详细说明,请参阅重新验证的工作原理。

Cache Components#

Cache Components 默认与 Next.js 一起工作,并非仅限 CDN 使用的功能。这包括作为 Node.js 服务器部署(通过 next start)以及与 Docker 容器一起使用。

与 CDN 配合使用#

在 Next.js 应用程序前使用 CDN 时,如果访问了动态 API,页面将包含 Cache-Control: private 响应头。这确保生成的 HTML 页面被标记为不可缓存。如果页面完全预渲染为静态,则会包含 Cache-Control: public,以允许页面在 CDN 上缓存。

如果你不需要静态和动态组件的混合,可以将整个路由设为静态,并将输出的 HTML 缓存到 CDN 上。如果不使用动态 API,这种自动静态优化(Automatic Static Optimization)就是运行 next build 时的默认行为。

有关 CDN 缓存行为、优雅降级和缓存可变性的详细指南,请参阅 CDN 缓存。有关不同平台对部分预渲染的支持,请参阅 PPR 平台指南 和部署适配器 API。

after#

使用 next start 自托管时,完全支持 after。

停止服务器时,请通过发送 SIGINT 或 SIGTERM 信号并等待来确保优雅关闭。Next.js 服务器会在退出前完成正在处理的请求,并执行任何待处理的 after() 回调。平台应允许配置一个排空期(建议 10-30 秒),以确保所有后台工作完成。

手动优雅关闭#

自托管时,你可能希望在服务器因 SIGTERM 或 SIGINT 信号关闭时运行一些代码。

你可以将环境变量 NEXT_MANUAL_SIG_HANDLE 设为 true,然后在 _document.js 文件中为该信号注册一个处理器。你需要直接在 package.json 的脚本中注册该环境变量,而不是在 .env 文件中。

小知识:手动信号处理在 next dev 中不可用。

package.json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "NEXT_MANUAL_SIG_HANDLE=true next start"
  }
}
pages/_document.js
if (process.env.NEXT_MANUAL_SIG_HANDLE) {
  process.on('SIGTERM', () => {
    console.log('Received SIGTERM: cleaning up')
    process.exit(0)
  })
  process.on('SIGINT', () => {
    console.log('Received SIGINT: cleaning up')
    process.exit(0)
  })
}
Next.js 中文网