Capítulo 208 de 456

deploymentId

Core Idea

deploymentId sets an identifier for a deployment used for version-skew protection and cache busting during rolling deployments, ensuring clients only load assets/Server Functions from a consistent version.

Key Concepts

  • deploymentId: string config option in next.config.js; also settable via NEXT_DEPLOYMENT_ID env var (config value takes precedence if both set).
  • Static asset cache busting: appends ?dpl=<deploymentId> to JS/CSS/image URLs.
  • Skew headers: adds x-deployment-id to client nav requests, x-nextjs-deployment-id to nav responses, data-dpl-id attribute on <html>.
  • Cache key inclusion: deploymentId is included in the 'use cache' cache key, invalidating entries when it changes.
  • Mismatch handling: client detects a mismatch via response header and triggers a hard navigation (full reload) instead of client-side nav.

Code Examples

module.exports = {
  deploymentId: 'my-deployment-id',
}
  • O que demonstra: configurar um deployment ID fixo.
NEXT_DEPLOYMENT_ID=my-deployment-id next build
  • O que demonstra: setar via variável de ambiente em vez de config.
module.exports = {
  deploymentId: process.env.DEPLOYMENT_VERSION || process.env.GIT_SHA,
}
  • O que demonstra: usar um valor derivado de CI (git SHA) pra múltiplas instâncias do mesmo deploy.

Reference Tables

VersionChanges
v16.2.0Pages Router detecta 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: Next.js não lê esse parâmetro nas requisições, ele é só pra cache busting; roteamento por deployment precisa vir do host/CDN.
  • Deploy rolling sem deploymentId consistente: instâncias diferentes podem servir mix de assets antigos/novos e causar erros.

Key Takeaways

  1. Todas as instâncias do mesmo deploy devem usar o mesmo deploymentId.
  2. Sem roteamento por deployment no host/CDN, clientes que caem em instância de outro deploy recarregam em vez de navegar client-side.
  3. Usado junto com use cache: mudar o deploymentId invalida entradas de cache automaticamente.

Connects To

  • generateBuildId: quando deploymentId está setado, o build ID vira constante e generateBuildId perde efeito.
  • Self-Hosting / Version Skew: guia relacionado sobre proteção de skew.
AnteriorcssChunkingPróximodevIndicators