Corrigir erros de carregamento de blocos Next.js em produção

Pré-requisitos

Este guia cobre o App Router em Next.js 14 a 16 (a versão atual é 16.3.8 em 4 de outubro de 2026) e usa a versão Node.js que sua versão Next.js exige (Next.js 16 precisa de Node.js 20.9 ou posterior). Correção de 5 exemplos usando Workbox 7.x. Verifique suas versões antes de aplicar qualquer alteração:

next --version
node --version

Por que erros de chunk load assombram a produção

O ChunkLoadErrorfrequentemente aparecido em consoles de navegador como “Falha ao carregar o pedaço (hash)” (webpack) ou “Falha ao carregar o pedaço /_next/static/chunks/…” (Turbopack), é uma falha de produção comum em aplicativos Next.js usando o App Router. Ele é acionado quando o navegador tenta buscar um pedaço de JavaScript dividido por código por meio de uma dinâmica import() chamada e recebe uma resposta diferente de 200 ou conteúdo que não pode ser analisado como JavaScript.

O resultado: navegação interrompida no lado do cliente e telas em branco. Os usuários param de confiar totalmente na navegação do lado do cliente.

Este erro não é reproduzido localmente. O desenvolvimento local executa uma única implantação em um único ambiente, sem camada CDN, sem proxy reverso e sem documentos HTML obsoletos em cache que façam referência a hashes de blocos desatualizados.

Este erro não é reproduzido localmente. O desenvolvimento local executa uma única implantação em um único ambiente, sem camada CDN, sem proxy reverso e sem documentos HTML obsoletos em cache que façam referência a hashes de blocos desatualizados. As condições que desencadeiam a falha na produção simplesmente não existem localhost:3000.

Este guia é um manual de diagnóstico em primeiro lugar, em vez de uma única solução mágica. O erro tem pelo menos cinco causas principais distintas e aplicar a correção errada é uma perda de tempo enquanto os usuários continuam acessando páginas quebradas. A árvore de decisão diagnóstica abaixo fornece um ponto de partida estruturado para cada ocorrência.

Como funciona a divisão de código Next.js (e onde ela quebra)

URLs de pedaços baseados em hash

Next.js divide automaticamente pacotes de aplicativos em arquivos discretos armazenados em _next/static/chunks/. Next.js fornece a cada arquivo um nome de arquivo com hash de conteúdo, o que significa que o hash muda sempre que o conteúdo do arquivo muda. Durante a navegação do lado do cliente, o App Router aciona import() chamadas para buscar apenas os pedaços necessários para a rota de destino. Isso reduz o tamanho da transferência inicial ao adiar o código não crítico, mas introduz uma dependência: o URL do bloco incorporado no JavaScript atualmente carregado deve ser resolvido para um arquivo JavaScript válido no servidor ou CDN.

Os três pontos de falha

Todo ChunkLoadError rastreia até um dos três locais no ciclo de vida da solicitação:

1. Origem ou CDN. O arquivo chunk está ausente do servidor, normalmente porque uma nova implantação substituiu o _next/static/ diretório e os arquivos com hash antigos não existem mais. Alternativamente, o CDN retorna o conteúdo errado (como uma página de erro HTML) para o URL do bloco.
2. Caminho de rede. Um proxy, camada de middleware ou firewall de aplicativo da Web intercepta a solicitação de bloco e retorna algo diferente do JavaScript esperado. Isso inclui middleware de autenticação que redireciona solicitações não autenticadas para uma página de login e proxies corporativos que injetam páginas de bloqueio.
3. Cache do cliente. O navegador contém um documento HTML obsoleto que faz referência a hashes de partes de uma implantação anterior. Quando o usuário navega, o import() call solicita um hash que não existe mais na origem atual.

Árvore de decisão diagnóstica

O fluxograma numerado a seguir fornece um caminho sistemático do sintoma à causa raiz. Cada ramificação do terminal faz referência à seção de correção correspondente abaixo.

1. O URL do bloco com falha pode ser capturado? Abra o console do navegador, localize o URL completo no ChunkLoadError mensagem (por exemplo, https://example.com/_next/static/chunks/app/dashboard-a1b2c3d4.js) e copie-o.
2. Inspecione o URL com falha com curl. Correr curl -sI para inspecionar cabeçalhos de resposta (código de status, content-type, cache-control), então execute curl -s | head -c 80 para confirmar se o corpo da resposta começa com JavaScript, não HTML (por exemplo, os primeiros bytes não devem ser or {"error").
   • Status diferente de 200, tipo de conteúdo incorreto ou corpo HTML → prossiga para o CDN / filial de origem (etapa 3).
   • 200, tipo de conteúdo correto e corpo JavaScript → prossiga para o Filial cliente/proxy (etapa 4).
3. Filial CDN/Origem:
   • Existe distorção na implantação? Verifique se o hash do pedaço na URL corresponde à compilação implantada atualmente. → Ver Correção 1: elimine a distorção de implantação com deploymentId.
   • O cache do CDN foi eliminado após a implantação? Verifique se há 404s em cache desatualizados ou páginas de erro HTML desatualizadas. → Ver Correção 3: cache CDN e higiene do cabeçalho do cache.
   • São _next/static/ ativos servidos com immutable cabeçalhos de cache? → Ver Correção 3.
4. Filial cliente/proxy:
   • O middleware intercepta _next/static/* caminhos? Teste curling com e sem cookies de autenticação. → Ver Correção 2: audite seu matcher de middleware.
   • Um service worker está servindo pedaços obsoletos de um pré-cache? Verifique o painel Aplicativo no DevTools. → Ver Correção 5: Service Workers e conflitos de cache offline.
   • Um bloqueador de anúncios ou proxy corporativo está reescrevendo a resposta? Teste a partir de um perfil de navegador limpo.

A seguir curl comandos fornecem as verificações de cabeçalho e corpo mencionadas acima. Substitua os URLs de espaço reservado pelos URLs de bloco reais:

curl -sI https://example.com/_next/static/chunks/app/dashboard-a1b2c3d4.js


curl -s https://example.com/_next/static/chunks/app/dashboard-a1b2c3d4.js | head -c 80


curl -s -D - -o /dev/null https://example.com/_next/static/chunks/app/dashboard-a1b2c3d4.js \
  | grep -iE "HTTP/|content-type|cache-control|x-nextjs-deployment-id"



curl -sI -b "session=abc123" https://example.com/_next/static/chunks/app/dashboard-a1b2c3d4.js
curl -sI https://example.com/_next/static/chunks/app/dashboard-a1b2c3d4.js

Se as respostas autenticadas e não autenticadas diferirem no código de status ou no tipo de conteúdo, o middleware é o provável culpado.

Correção 1: elimine a distorção de implantação com deploymentId

O que é implantação distorcida

A distorção da implantação ocorre quando os usuários têm guias abertas do navegador contendo um documento HTML de uma implantação anterior. Esse HTML contém