Capítulo 396 de 456

deploymentId

Core Idea

Define um identificador de deployment usado para proteção contra version skew e cache busting durante deploys rolling.

Key Concepts

  • deploymentId: string identificadora do deployment atual; tem precedência sobre NEXT_DEPLOYMENT_ID
  • NEXT_DEPLOYMENT_ID: variável de ambiente alternativa para setar o mesmo valor
  • version skew protection: mecanismo que evita mistura de assets entre versões antiga/nova durante rollout

Code Examples

module.exports = {
  deploymentId: 'my-deployment-id',
}
  • O que demonstra: configuração estática do deployment ID.
NEXT_DEPLOYMENT_ID=my-deployment-id next build
  • O que demonstra: setar via variável de ambiente no build.
module.exports = {
  deploymentId: process.env.DEPLOYMENT_VERSION || process.env.GIT_SHA,
}
  • O que demonstra: usar SHA do commit ou versão como ID em ambientes multi-servidor atrás de load balancer.

Reference Tables

VersionChanges
v16.2.0Pages Router detecta version skew pelo header de resposta em vez do build ID; build ID fica constante quando deploymentId está setado
v14.1.4deploymentId estabilizado como opção top-level
v13.4.10experimental.deploymentId introduzido

Anti-patterns

  • Esperar que ?dpl= faça roteamento por versão: Next.js não lê esse query param nas requests recebidas, ele serve só pra cache busting; roteamento por deployment precisa vir do host/CDN

Key Takeaways

  1. Quando configurado, o Next.js: acrescenta ?dpl=<id> em assets estáticos, adiciona headers x-deployment-id/x-nextjs-deployment-id, injeta data-dpl-id no <html>, e inclui o ID na cache key do 'use cache'
  2. Mismatch de deployment ID entre client e server dispara hard navigation (reload completo) em vez de navegação client-side
  3. Em multi-servidor, todas as instâncias do mesmo deployment devem compartilhar o mesmo deploymentId
  4. Sem roteamento por deployment no host/CDN, clientes que caem numa instância de outro deployment durante rollout apenas recarregam, não navegam corretamente

Connects To

  • generateBuildId: opção relacionada de identificação de build
  • 'use cache' directive: deploymentId entra na cache key dessa diretiva
AnteriorcrossOriginPróximodevIndicators