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

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

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

图片优化

通过 next/image 实现的图片优化在使用 next start 部署时可零配置自托管。如果您希望使用单独的服务优化图片，可以配置图片加载器。

通过静态导出时，可在 next.config.js 中定义自定义图片加载器来使用图片优化。请注意图片是在运行时优化，而非构建时。

须知：

在基于 glibc 的 Linux 系统上，图片优化可能需要额外配置以防止内存使用过量。

了解优化图片的缓存行为及如何配置 TTL。

您也可以禁用图片优化同时保留使用 next/image 的其他优势。例如，如果您已自行优化图片。

中间件

中间件在使用 next start 部署时可零配置自托管。由于需要访问传入请求，静态导出时不支持中间件。

中间件使用 Edge 运行时，这是所有可用 Node.js API 的子集，有助于确保低延迟，因为它可能在应用的每个路由或资源前运行。如果不希望如此，可以使用完整的 Node.js 运行时运行中间件。

如果需要添加使用全部 Node.js API 的逻辑（或外部包），可将此逻辑移至布局作为服务器组件。例如，检查头信息和重定向。也可以通过 next.config.js 使用头信息、cookie 或查询参数进行重定向或重写。如果不可行，还可使用自定义服务器。

环境变量

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

默认情况下，环境变量仅在服务器端可用。要在浏览器中暴露环境变量，必须添加 NEXT_PUBLIC_ 前缀。但这些公共环境变量会在 next build 期间内联到 JavaScript 包中。

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

import { connection } from 'next/server'

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

import { connection } from 'next/server'

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

这允许您使用单一的 Docker 镜像，在不同环境中使用不同的值进行升级。

须知：

您可以使用 register 函数在服务器启动时运行代码。

不建议使用 runtimeConfig 选项，因为它不适用于独立输出模式。建议逐步采用应用路由器。

缓存与 ISR

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

缓存和重新验证页面（使用增量静态再生）使用相同的共享缓存。默认情况下，此缓存存储在 Next.js 服务器的文件系统（磁盘）上。这在自托管时自动工作，适用于页面路由器和应用路由器。

如果需要将缓存页面和数据持久化到持久存储，或在多个容器或 Next.js 应用实例间共享缓存，可以配置 Next.js 缓存位置。

自动缓存

Next.js 为真正不可变的资源设置 Cache-Control 头为 public, max-age=31536000, immutable。无法覆盖。这些不可变文件在文件名中包含 SHA 哈希，因此可以安全地无限期缓存。例如，静态图片导入。可以配置 TTL 用于图片。
增量静态再生 (ISR) 设置 Cache-Control 头为 s-maxage: <在 getStaticProps 中重新验证>, stale-while-revalidate。此重新验证时间在 getStaticProps 函数中以秒为单位定义。如果设置 revalidate: false，则默认为一年缓存时长。
动态渲染的页面设置 Cache-Control 头为 private, no-cache, no-store, max-age=0, must-revalidate 以防止用户特定数据被缓存。这适用于应用路由器和页面路由器。也包括草稿模式。

静态资源

如果希望在不同域名或 CDN 上托管静态资源，可以在 next.config.js 中使用 assetPrefix 配置。Next.js 在获取 JavaScript 或 CSS 文件时将使用此资源前缀。将资源分离到不同域名的缺点是额外的 DNS 和 TLS 解析时间。

了解更多关于 assetPrefix。

配置缓存

默认情况下，生成的缓存资源将存储在内存（默认为 50mb）和磁盘上。如果使用 Kubernetes 等容器编排平台托管 Next.js，每个 pod 都会有缓存的副本。为防止显示过时数据（因为默认情况下缓存不在 pod 间共享），可以配置 Next.js 缓存以提供缓存处理程序并禁用内存缓存。

自托管时配置 ISR/数据缓存位置，可在 next.config.js 文件中配置自定义处理程序：

next.config.js

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

然后，在项目根目录创建 cache-handler.js，例如：

cache-handler.js

const cache = new Map()

module.exports = class CacheHandler {
  constructor(options) {
    this.options = options
  }

  async get(key) {
    // 可以存储在任何地方，如持久存储
    return cache.get(key)
  }

  async set(key, data, ctx) {
    // 可以存储在任何地方，如持久存储
    cache.set(key, {
      value: data,
      lastModified: Date.now(),
      tags: ctx.tags,
    })
  }

  async revalidateTag(tags) {
    // tags 是字符串或字符串数组
    tags = [tags].flat()
    // 遍历缓存中的所有条目
    for (let [key, value] of cache) {
      // 如果值的标签包含指定标签，删除此条目
      if (value.tags.some((tag) => tags.includes(tag))) {
        cache.delete(key)
      }
    }
  }

  // 如果想为单个请求设置临时内存缓存，并在下一个请求前重置，可以使用此方法
  resetRequestCache() {}
}

使用自定义缓存处理程序可确保所有托管 Next.js 应用的 pod 间的一致性。例如，可以将缓存值保存在任何地方，如 Redis 或 AWS S3。

须知：

revalidatePath 是缓存标签上的便利层。调用 revalidatePath 将使用提供的页面的特殊默认标签调用 revalidateTag 函数。

构建缓存

Next.js 在 next build 期间生成 ID 以标识正在服务的应用版本。相同的构建应被使用并在多个容器中启动。

如果为环境的每个阶段重新构建，需要在容器间生成一致的构建 ID。在 next.config.js 中使用 generateBuildId 命令：

next.config.js

module.exports = {
  generateBuildId: async () => {
    // 可以是任何内容，使用最新的 git 哈希
    return process.env.GIT_HASH
  },
}

版本偏差

Next.js 会自动缓解大多数版本偏差实例，并在检测到不匹配时自动重新加载应用以获取新资源。例如，如果 deploymentId 不匹配，页面间转换将执行硬导航而非使用预取值。

当应用重新加载时，如果未设计为在页面导航间持久化，可能会丢失应用状态。例如，使用 URL 状态或本地存储将在页面刷新后保持状态。但组件状态如 useState 将在此类导航中丢失。

流式传输与 Suspense

Next.js 应用路由器在自托管时支持流式响应。如果使用 Nginx 或类似代理，需要配置禁用缓冲以启用流式传输。

例如，可以通过设置 X-Accel-Buffering 为 no 在 Nginx 中禁用缓冲：

next.config.js

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

部分预渲染

部分预渲染（实验性）默认与 Next.js 一起工作，不是仅限 CDN 的功能。这包括作为 Node.js 服务器部署（通过 next start）和使用 Docker 容器时。

与 CDN 一起使用

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

如果不需要混合静态和动态组件，可以使整个路由静态并在 CDN 上缓存输出 HTML。如果不使用动态 API，运行 next build 时自动静态优化是默认行为。

随着部分预渲染趋于稳定，我们将通过部署适配器 API 提供支持。

`after`

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

停止服务器时，确保通过发送 SIGINT 或 SIGTERM 信号并等待来实现优雅关闭。这允许 Next.js 服务器等待直到 after 内使用的待处理回调函数或承诺完成。

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

On this page