NNext.js 中文网 GitHub

deploymentId

配置用于版本偏差保护和缓存清除的部署标识符。

deploymentId 选项允许你为部署设置一个标识符。此标识符用于版本偏差(version skew)保护和滚动部署期间的缓存清除。

next.config.js
module.exports = {
  deploymentId: 'my-deployment-id',
}

你还可以使用 NEXT_DEPLOYMENT_ID 环境变量设置部署 ID:

bash
NEXT_DEPLOYMENT_ID=my-deployment-id next build

小知识: 非空的 NEXT_DEPLOYMENT_ID 环境变量优先级高于 next.config.js 中的 deploymentId 值。

工作原理#

当配置了 deploymentId 时,Next.js 会:

  1. 在静态资源 URL(JavaScript、CSS、图片)后附加 ?dpl=<deploymentId>
  2. 向客户端导航请求添加 x-deployment-id 头
  3. 向导航响应添加 x-nextjs-deployment-id 头
  4. 在 <html> 元素上注入 data-dpl-id 属性
  5. 将 deploymentId 包含在 'use cache' 缓存键中,当部署 ID 更改时使缓存条目失效

当客户端检测到其部署 ID 与服务器的不一致时(通过响应头),它会触发硬导航(整页重新加载),而不是客户端导航。这确保用户始终从一致的部署版本接收资源 和 Server Functions。

小知识: Next.js 不会读取传入请求上的 ?dpl= 查询参数。该查询参数用于缓存清除(确保浏览器和 CDN 获取最新资源),而非路由。如果你需要感知版本的路由,请查阅你的托管提供商或 CDN 的文档,了解如何实现基于部署的路由。

用例#

滚动部署#

在滚动部署期间,某些服务器实例可能正在运行新版本,而其他实例仍在运行旧版本。如果没有部署 ID,用户可能会同时收到新旧资源,从而导致错误。

为每次部署设置一致的 deploymentId 可确保:

  • 客户端始终从匹配的部署版本请求资源
  • 不匹配时触发整页重新加载以获取正确的资源
  • Server Functions 能够跨部署边界正常工作
  • 客户端始终从匹配的部署版本请求资源
  • 不匹配时触发整页重新加载以获取正确的资源

多服务器环境#

在负载均衡器后面运行 Next.js 应用程序的多个实例时,同一部署的所有实例都应使用相同的 deploymentId。

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

只有当请求也按部署进行路由时,按部署设置的值才能避免偏差。Next.js 不会基于 ?dpl= 进行路由,因此该路由来自你的托管商或 CDN。如果没有它,在滚动发布期间访问到另一个部署实例的客户端将重新加载,而不是进行导航。

版本历史#

版本变更
v16.2.0Pages Router 从响应头而非构建 ID 检测版本偏差,且当设置了 deploymentId 时,构建 ID 保持恒定。
v14.1.4deploymentId 稳定为顶层配置选项。
v13.4.10引入 experimental.deploymentId。

相关#

Next.js 中文网