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 会:
- 在静态资源 URL(JavaScript、CSS、图片)后附加
?dpl=<deploymentId> - 向客户端导航请求添加
x-deployment-id头 - 向导航响应添加
x-nextjs-deployment-id头 - 在
<html>元素上注入data-dpl-id属性 - 将
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.0 | Pages Router 从响应头而非构建 ID 检测版本偏差,且当设置了 deploymentId 时,构建 ID 保持恒定。 |
v14.1.4 | deploymentId 稳定为顶层配置选项。 |
v13.4.10 | 引入 experimental.deploymentId。 |