How to self-host your Next.js application

在部署你的 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 的逻辑（或使用外部包），你可能能够将此逻辑移动到布局作为服务器组件。例如，检查headers和重定向。你也可以使用 headers、cookies 或查询参数通过 next.config.js 进行重定向或重写。如果这不起作用，你也可以使用自定义服务器。

环境变量

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

默认情况下，环境变量仅在服务器上可用。要将环境变量暴露给浏览器，它必须以 NEXT_PUBLIC_ 为前缀。但是，这些公共环境变量将在 next build 期间内联到 JavaScript 包中。

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

这允许你使用一个单一的 Docker 镜像，可以通过具有不同值的多个环境进行推广。

需要了解：

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

我们不建议使用 runtimeConfig 选项，因为这不适用于独立输出模式。相反，我们建议逐步采用 App Router。

缓存和 ISR

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

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

如果你希望将缓存的页面和数据持久化到持久存储，或在多个容器或 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，它将默认为一年的缓存持续时间。
动态渲染的页面设置 Cache-Control 头为 private, no-cache, no-store, max-age=0, must-revalidate 以防止用户特定数据被缓存。这适用于 App Router 和 Pages Router。这也包括草稿模式。

静态资产

如果你希望在不同的域或 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() // 将 tags 转换为数组
    // 遍历缓存中的所有条目
    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 hash
    return process.env.GIT_HASH
  },
}

版本偏差

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

当应用程序重新加载时，如果它没有设计为在页面导航之间持久化，可能会有应用程序状态丢失。例如，使用 URL 状态或本地存储将在页面刷新后持久化状态。但是，像 useState 这样的组件状态在这样的导航中会丢失。

手动优雅关闭

在自托管时，你可能希望在服务器在 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)
  })
}