SEO programático · ·
Apêndice: decidir quando as páginas são geradas
Entender o impacto de geração antecipada, cache e atendimento sob demanda no custo; conferir versão e configuração do Next.js.
Este capítulo faz parte do curso gratuito SEO programático.
Este apêndice ajuda a conversar com a equipe que implementará o projeto. Build é a preparação da aplicação para publicação; gerar páginas nessa etapa antecipa trabalho, enquanto atender sob demanda desloca parte do custo para o uso. Nenhum dos regimes é o melhor em toda situação.
Os exemplos dependem da versão e das configurações do Next.js. A documentação consultada em 28/10/2026 identifica a versão 16.4.3. Antes de copiar código, confira a versão instalada, o uso de Cache Components e os requisitos da rota. Para a decisão executiva, peça a comparação de tempo de publicação, consumo de recursos e experiência do primeiro visitante.
Ver como texto
Comparação entre o vocabulário do material anterior ao Next.js 16 e o vocabulário atual: experimental.ppr virou cacheComponents no topo do next.config, experimental_ppr de segmento foi removido, params passou a ser Promise, o requisito de parâmetros depende da configuração da rota e o cache passou a ter a diretiva use cache com três variantes.
Configuração explícita. Na documentação de Cache Components atualizada em 15/10/2026, cacheComponents: true habilita esse modelo de cache e pré-renderização. A orientação atual também pede declarar partialPrefetching explicitamente; seu valor deve seguir a migração e a versão adotadas. Isso não significa que todo projeto Next.js 16 já opere nesse regime.
// next.config.ts — exemplo para a configuração documentada em 15/10/2026
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
cacheComponents: true,
partialPrefetching: true,
};
export default nextConfig;
// Confirme a versão instalada e siga o guia de migração do projeto.Existe um efeito colateral que pega gente desprevenida e que não tem nada a ver com cache de dados. Com cacheComponents ligado, o Next passa a usar o <Activity> do React para preservar estado de componente durante a navegação client-side: rotas recentes ficam montadas em modo hidden em vez de serem desmontadas. Na prática, um dropdown que você achava que fechava sozinho ao trocar de página continua aberto, um dialog mantém o estado e os efeitos são limpos quando a rota fica oculta e recriados quando ela volta a ficar visível. Se você ligar a flag e a navegação passar a se comportar de um jeito estranho, esse é o primeiro lugar para olhar.
Ver como texto
Três modos de generateStaticParams com medidores de custo: gerar tudo no build tem custo alto de build e primeira visita HTML antecipado; gerar um subconjunto limita o build e deixa a cauda longa lenta na primeira visita; não gerar nada custa menor, não nulo no build, deixa toda página lenta na primeira visita e é bloqueado quando Cache Components está ligado.
Há três decisões possíveis para o conjunto de páginas: gerar tudo antecipadamente, gerar um lote prioritário ou deixar caminhos para atendimento posterior. As opções aceitas e a política de cache dependem da configuração. O tempo até o primeiro conteúdo visível também depende de rede, dados e aplicação; uma página pré-gerada não torna a visita literalmente instantânea.
Peça ao time que demonstre o caminho mais visitado, um caminho fora do lote e uma combinação inexistente. Esses três casos revelam mais sobre o desenho do que apenas um build concluído.

Fonte: nextjs.org · Captura em 29/10/2026 · trecho de página pública
Ver como texto
Captura da documentação oficial: função para gerar rotas e relação com o momento de construção.
Array vazio depende da configuração. A referência atual exige ao menos um conjunto completo de parâmetros para uma rota dinâmica que usa ensureStatic = "navigation". Não transforme essa condição em uma proibição geral para todo projeto com Cache Components. Confira a referência correspondente à versão instalada e valide a rota real antes de adotar parâmetros artificiais para apenas satisfazer o build.
No Radar, projeto hipotético, o lote inicial deve seguir as localidades com dados úteis e a prioridade definida anteriormente. Gere uma amostra, registre tempo e memória e compare com o limite de publicação. Só então decida quanto antecipar. A matriz nacional, por si só, não prova que um build é inviável; a quantidade de dados e o trabalho por página também importam.
// src/app/combustivel/[municipio]/[produto]/page.tsx
import { notFound } from "next/navigation";
import { lotePrioritario, serieSemanal } from "@/lib/radar-anp";
// Exemplo didático: a configuração de atendimento fora do lote deve seguir
// o regime de cache adotado. Não misture opções de migrações diferentes.
export async function generateStaticParams() {
// o lote priorizado que você já definiu, e não a matriz inteira.
// fetch é memoizado entre generateStaticParams, generateMetadata e a page,
// então ler a mesma fonte aqui e lá embaixo não dobra a chamada de rede.
const lote = await lotePrioritario();
return lote.map((registro) => ({
municipio: registro.municipioSlug, // ASCII, ex.: "sao-paulo-sp"
produto: registro.produtoSlug, // ASCII, ex.: "gasolina-comum"
}));
}
type Params = { municipio: string; produto: string };
export async function generateMetadata({ params }: { params: Promise<Params> }) {
// params é Promise desde o Next 15. Sem o await, não compila.
const { municipio, produto } = await params;
const serie = await serieSemanal(municipio, produto);
if (!serie) return {};
return {
title: `Preço de ${serie.produtoNome} em ${serie.municipioNome} (${serie.uf})`,
alternates: { canonical: `/combustivel/${municipio}/${produto}` },
};
}
export default async function Page({ params }: { params: Promise<Params> }) {
const { municipio, produto } = await params;
const serie = await serieSemanal(municipio, produto);
// par válido no IBGE mas sem coleta da ANP naquele município: não existe página.
if (!serie) notFound();
return (
<article>
<h1>
Preço de {serie.produtoNome} em {serie.municipioNome}
</h1>
<p>
Média da semana de {serie.semanaReferencia}: R$ {serie.precoMedio.toFixed(2)}
</p>
</article>
);
}O comportamento de um endereço fora do lote precisa ser deliberado. Em configurações que usam dynamicParams, a opção controla o tratamento de parâmetros não gerados antecipadamente. Com Cache Components, confira as regras de migração e de geração da versão adotada em vez de misturar opções de modelos diferentes.
Independentemente do regime, a aplicação deve consultar o inventário real e tratar uma combinação inexistente. No exemplo, notFound() expressa essa decisão. Um endereço válido do cadastro territorial não demonstra que existe dado de combustível para publicar.
Ver como texto
Multiplicador de segmentos aninhados: cada param do segmento pai abre um leque de params no segmento filho. Com 27 params no pai e 5 por pai no filho são 135 combinações de parâmetros; a função do filho é chamada uma vez por conjunto do pai. A mesma estrutura aplicada às localidades do lote do IBGE, multiplicada pelos combustíveis, chega a dezenas de milhares de execuções.
Quatro fatos versionados que mudam decisão de arquitetura e que raramente aparecem juntos
- Durante revalidação incremental,
generateStaticParamsnão é chamado de novo. A lista de rotas conhecidas é uma foto do build. Página nova no seu banco não vira rota estática sozinha, o comportamento fora do lote depende do regime de geração e cache adotado. - A função também funciona em
layout.tsxe em Route Handlers. Emroute.tsisso permite pré-gerar respostas de API no build, o que é útil quando o front consome um JSON por município. - Escopo por arquivo. Um
page.tsxem[category]/[product]pode gerar params para os dois níveis; umlayout.tsxem[category]só gera para o próprio nível. Nunca se gera params abaixo do próprio nível. fetché memoizado automaticamente entre funçõesgenerate*, layouts, pages e Server Components. Ler a mesma URL nogenerateStaticParamse depois na página não dobra a chamada de rede, o que muda o cálculo de quando vale a pena passar dado por argumento.

Fonte: support.google.com · Captura em 29/10/2026 · trecho de página pública
Ver como texto
Captura da documentação oficial: categorias do relatório de páginas indexadas e motivos de exclusão.
As três variantes de cache que existem hoje: 'use cache' (padrão, LRU em memória no runtime), 'use cache: remote' (handler dedicado da plataforma, com roundtrip de rede para checar o cache e, segundo a própria documentação, tipicamente com custo de plataforma) e 'use cache: private', para quando não dá para refatorar e tirar o dado de request de dentro do escopo. As restrições que quebram código real: não chame cookies(), headers() nem leia searchParams dentro de escopo cacheado, leia fora e passe como argumento; argumentos e retornos precisam ser serializáveis, com instâncias de URL, funções, Symbols, WeakMap e WeakSet explicitamente recusados; e variáveis capturadas por closure entram na chave de cache automaticamente, o que produz o bug silencioso mais chato do conjunto, o cache que nunca acerta porque a chave muda sem você ver.
// src/lib/radar-anp.ts
import { cacheLife, cacheTag } from "next/cache";
type Serie = {
municipioNome: string;
uf: string;
produtoNome: string;
semanaReferencia: string;
precoMedio: number;
};
export async function serieSemanal(
municipio: string,
produto: string,
): Promise<Serie | null> {
"use cache";
// Perfil ilustrativo: alinhe a política ao ciclo observado da fonte.
// Revalidação não é promessa de atualização em horário fixo: confira
// ingestão, invalidação e atendimento de uma página após a mudança.
cacheLife("days");
// tag por município permite invalidar só o que mudou quando a planilha sai.
cacheTag(`radar-anp:${municipio}`);
const resposta = await fetch(
`https://exemplo.interno/radar/anp/${municipio}/${produto}`,
{ headers: { accept: "application/json" } },
);
if (resposta.status === 404) return null;
if (!resposta.ok) throw new Error(`ANP respondeu ${resposta.status}`);
return (await resposta.json()) as Serie;
}Ver como texto
Os sete perfis oficiais de cacheLife desenhados sobre um eixo de tempo em escala logarítmica, de um segundo a um ano. Cada barra começa no revalidate e termina no expire, e o círculo vazado marca o stale. O perfil seconds termina dentro da faixa tracejada de expire abaixo de cinco minutos, que sai do prerender e vira dynamic hole. Os perfis days e weeks aparecem destacados como a faixa compatível com um dado semanal.
A linha do seconds merece atenção porque ela decide arquitetura, e não desempenho. Caches de vida muito curta, com revalidate zero ou expire abaixo de 5 minutos, são automaticamente excluídos do prerender e viram dynamic holes. Isso inclui o perfil seconds inteiro. A diferença entre escolher seconds e escolher days não é o dado ficar mais fresco por alguns minutos: é a página ser HTML estático ou ser uma função que roda a cada request, com o custo e a latência que vêm junto.
O Radar tem um ritmo declarado pela fonte, e a fonte é semanal. Escolher seconds porque "quanto mais fresco melhor" transforma cada página de município em invocação de função para servir um número que só muda na sexta-feira. days revalida uma vez por dia e expira em uma semana, o que cobre o ciclo com folga. weeks revalida a cada semana e expira em 30 dias, mais barato e alinhado à publicação, com o risco de servir o número da semana anterior se a ANP atrasar. Qualquer uma das duas se defende; o que não se defende é escolher sem citar o ciclo do dado.
Duas regras que evitam erro de configuração: expire precisa ser maior que revalidate, senão o Next levanta erro; e o router client impõe mínimo de 30 segundos de stale para que links já prefetchados continuem utilizáveis. Em cache aninhado sem cacheLife explícito no externo, o interno mais curto encurta o externo, e o interno mais longo não estende além do default. Quando o build travar com "Filling a cache during prerender timed out", a leitura é uma só: alguma Promise de dado dinâmico está atravessando a fronteira do use cache. Rode com NEXT_PRIVATE_DEBUG_CACHE=1 para ver qual.
- Etapa 1 de 5: Versão e cache
Evidência para escolher: versão instalada e guia de migração correspondente.
- Etapa 2 de 5: Lote antecipado
Evidência para escolher: páginas úteis, tempo e memória medidos no build.
- Etapa 3 de 5: Fora do lote
Evidência para escolher: teste de caminho válido e combinação inexistente.
- Etapa 4 de 5: Atualização
Evidência para escolher: período da fonte, ingestão e invalidação verificadas.
- Etapa 5 de 5: Custo
Evidência para escolher: publicação, consultas, memória e armazenamento do piloto.
Ver como texto
- Versão e cache: Evidência para escolher: versão instalada e guia de migração correspondente.
- Lote antecipado: Evidência para escolher: páginas úteis, tempo e memória medidos no build.
- Fora do lote: Evidência para escolher: teste de caminho válido e combinação inexistente.
- Atualização: Evidência para escolher: período da fonte, ingestão e invalidação verificadas.
- Custo: Evidência para escolher: publicação, consultas, memória e armazenamento do piloto.
Sua etapa do projeto. Coloque a rota dinâmica do Radar no ar gerando o lote priorizado de [Priorizar páginas pela necessidade do público](#keywords-sem-volume-confiavel), com as escolhas de geração, cache e atualização registradas.
Critérios de aceite
- O lote priorizado entra no build e um par fora do lote responde 200 na primeira visita, confirmando o comportamento esperado na configuração escolhida.
- Um par que existe no IBGE mas não tem coleta da ANP devolve 404, e não uma página com espaço vazio.
- O perfil de
cacheLifeestá escrito no código com um comentário de uma linha ligando a escolha ao ciclo semanal da fonte. - O tempo de build está medido e anotado, com o número de páginas do lote ao lado. Rode
npm run buildcronometrado, guarde o par (páginas, segundos) e você terá a única base honesta para decidir, no apêndice técnico [Apêndice: medir velocidade e capacidade da plataforma](#performance-e-teto-de-plataforma), quanto do catálogo cabe no build.

Fonte: web.dev · Captura em 29/10/2026 · trecho de página pública
Ver como texto
Captura da documentação oficial: lCP, INP e CLS como medidas diferentes de experiência.
Leve quatro perguntas à próxima reunião com o time técnico. (1) Um acervo de 12.000 páginas cujo dado muda uma vez por mês pede qual modo de generateStaticParams, qual regra de atendimento fora do lote e qual perfil de cacheLife, com um argumento para cada escolha? (2) Em qual configuração a documentação exige parâmetros e que risco existe em usar um parâmetro artificial? (3) Com um segmento pai de 300 params e um filho de 8 por pai, quantas vezes o filho executa no build, e quanto isso pesa no tempo de CI? (4) O que muda no artefato servido quando alguém troca days por seconds numa página que já está no ar?
O guia abaixo é para quem contrata ou cobra a equipe que implanta, sem precisar abrir o código. Ele converte as quatro alavancas deste capítulo em entregas verificáveis e destrava uma decisão concreta: quanto do catálogo cabe no build sem estourar prazo de publicação nem conta de hospedagem.
Guia de implementação: contratar a arquitetura de rotas do acervo
Cinco entregas que qualquer executivo confere sem ler uma linha de código.
Passo 1: Peça a ficha das quatro alavancas por rota
Cache Components, modo do generateStaticParams, dynamicParams e perfil de cacheLife, cada um com uma linha de justificativa.
Deu certo quando: Cada escolha cita o ciclo de atualização da fonte, como a publicação semanal da ANP.
Erro comum: Aceitar "deixamos o padrão do framework" como justificativa.
Passo 2: Exija o teste do par sem dado
Um endereço válido na lista de municípios, mas sem coleta, precisa responder 404.
Deu certo quando: O desenvolvedor mostra a resposta 404 ao vivo, no navegador ou no terminal.
Erro comum: Página publicada com um espaço vazio no lugar do dado, que é o padrão de doorway.
Passo 3: Meça o build com o lote piloto
Tempo de build cronometrado, anotado ao lado do número de páginas geradas.
Deu certo quando: O par páginas e segundos está registrado no repositório com data.
Erro comum: Projetar o tempo da matriz inteira sem ter medido nenhum lote.
Passo 4: Confronte o perfil de cache com a conta da plataforma
Perfil curto transforma página estática em função executada, e cobrada, a cada visita.
Deu certo quando: Nenhuma rota de acervo usa o perfil seconds sem justificativa escrita.
Erro comum: Escolher frescor máximo por garantia e pagar execução em toda visita.
Passo 5: Registre a decisão com dono e data de revisão
A ficha entra no registro do comitê trimestral que decide entre escalar, podar ou parar o acervo.
Deu certo quando: Ficha datada, com nome do responsável e data da próxima revisão.
Erro comum: Decisão verbal que desaparece na troca de fornecedor.
No fim você tem: Uma rota de acervo com regime de renderização escolhido por escrito, tempo de build medido e custo de hospedagem previsível.
| Etapa | Quem faz | Prazo e esforço | Como conferir |
|---|---|---|---|
| Ficha das quatro alavancas | Desenvolvedor, revisado pelo líder técnico | 2 a 4 horas; sem custo de licença | Uma linha de justificativa por alavanca, citando o ciclo da fonte |
| Teste do par sem dado | Desenvolvedor | 1 hora | Resposta 404 para um par sem coleta, mostrada ao vivo |
| Medição do build | Desenvolvedor | 1 hora por medição; minutos de CI já contratados | Par páginas e segundos anotado no repositório |
| Perfil de cache contra a conta | Líder técnico com quem paga a plataforma | 2 horas | Nenhum perfil seconds em rota de acervo sem justificativa |
| Registro no comitê | Dono do projeto, do marketing ou de produto | 30 minutos | Ficha datada, com responsável e data de revisão |
Guia prático: o pacote de segurança do Next.js de 30/09/2026. A versão estável passou a ser a 16.3.8, e a linha 15.5 recebeu a 15.5.27. Das sete falhas corrigidas, quatro tocam diretamente um acervo programático, porque envolvem o cache de páginas geradas e o controle de quais parâmetros viram página:
- envenenamento de cache em páginas SSG e ISR do Pages Router hospedadas fora da Vercel, que pode servir o conteúdo de outra rota a todos os visitantes até a próxima revalidação;
- envenenamento de cache quando uma rota catch-all na raiz convive com páginas SSG ou ISR, com uma única requisição forjada;
- rotas de imagem como opengraph-image ignorando dynamicParams em build com webpack, o que gera imagem para parâmetros excluídos de propósito do generateStaticParams;
- com Cache Components, conteúdo de rascunho do Draft Mode vazando para páginas publicadas.

Ver como texto
Publicação do blog do Next.js, em inglês, de quarta-feira, 30 de setembro de 2026, intitulada September 2026 Security Release, com o aviso de que as correções estão nas versões 16.3.8 e 15.5.27 e o terminal com os comandos npm install next@15.5.27 e npm install next@16.3.8.
Atualizar o acervo e provar que nenhuma página serviu conteúdo trocado
Cinco passos para o desenvolvedor, com a conferência final feita pelo analista de SEO. Prioridade alta para quem hospeda o Next.js fora da Vercel.
Passo 1: Descubra a versão em produção
Rode npm ls next no repositório e compare com a versão do último deploy.
Deu certo quando: A versão anotada é 16.3.8 ou 15.5.27, ou existe um chamado aberto para chegar lá.
Erro comum: Conferir o package.json com faixa de versão e supor que a produção já pegou a correção.
Passo 2: Classifique o acervo pelas quatro condições de risco
Hospedagem própria com Pages Router, catch-all na raiz, imagem de compartilhamento por rota com build webpack, Cache Components com Draft Mode.
Deu certo quando: Cada rota do acervo tem uma linha dizendo quais condições se aplicam.
Erro comum: Descartar o risco porque o site usa App Router, sem olhar o catch-all e as rotas de imagem.
Passo 3: Atualize e faça o deploy fora do horário de pico
Um build completo regenera as páginas estáticas e descarta entradas de cache antigas.
Deu certo quando: O deploy novo está no ar e a versão aparece correta no registro do build.
Erro comum: Atualizar só o ambiente de prévia e esquecer a produção.
Passo 4: Teste a rota de imagem com um parâmetro fora da lista
Peça a opengraph-image de um município ou produto que o generateStaticParams exclui com dynamicParams false.
Deu certo quando: A resposta é 404, igual à da página correspondente.
Erro comum: Testar só a página e deixar a rota de imagem gerando conteúdo para parâmetros proibidos.
Passo 5: Confira uma amostra de páginas contra o registro
Sorteie 20 páginas de grupos diferentes e compare título e dado principal com o registro de origem.
Deu certo quando: As 20 páginas mostram o dado da própria rota, sem conteúdo de outra página.
Erro comum: Conferir só a página inicial, que raramente passa pelo cache das rotas do acervo.
No fim você tem: Um acervo na versão corrigida, com prova escrita de que as páginas servem o próprio dado e de que nenhuma imagem nasce fora da lista.
![Página de referência do generateStaticParams na documentação do Next.js, em inglês, marcada como última versão 16.3.8 e atualizada em 25 de agosto de 2026, com a explicação de que a função gera rotas estáticas no build e o exemplo em app/blog/[slug]/page.tsx.](/educacao/seo-programatico/guias/nextjs-generate-static-params.webp)
Ver como texto
Página de referência do generateStaticParams na documentação do Next.js, em inglês, marcada como última versão 16.3.8 e atualizada em 25 de agosto de 2026, com a explicação de que a função gera rotas estáticas no build e o exemplo em app/blog/[slug]/page.tsx.
Peça hoje ao time técnico a ficha das quatro alavancas da rota principal do acervo, com entrega em até 14 dias. Na entrega, confira três provas: o par páginas e segundos medido no build, um 404 real para um par sem dado e nenhum perfil de cache mais curto que o ciclo da fonte.
Seu caderno neste capítulo
Abrir o caderno completoSelecione um trecho do capítulo para destacar ou anotar. Nos vídeos e áudios, use Anotar este momento. No teclado, selecione com Shift e as setas e use Alt+Shift+D para destacar ou Alt+Shift+N para anotar.
Salvo neste navegador. Entre na sua conta para levar o caderno a outros aparelhos.
Entre na sua conta para compartilhar o que aprendeu e convidar alguém para estudar com você.
Veja o que estudar antes e para onde seguir depois, explore os conceitos e compare abordagens em outros cursos. Sugestões marcadas como “sugerido pelo grafo” vêm dos assuntos em comum, não do índice do curso.
- Node.js: JavaScript no ServidorNext.js: organizar as páginas de um siteExaminar conexões de Next.js: organizar as páginas de um site
- Frontends com VibecodingEscolher a stack e projetar suas dependênciasExaminar conexões de Escolher a stack e projetar suas dependências
- Software e IA para executivosOnde a tela é montada: no servidor ou no celularExaminar conexões de Onde a tela é montada: no servidor ou no celular
Terminou a leitura?
Você está aqui: capítulo 19 de 21
0 de 21 concluídos
- Próximo · Capítulo 20 de 21 · 39 minApêndice: apresentar endereços e atualizações ao buscadorLer o capítulo 20 sem concluir
Marque como concluído para o capítulo contar no seu painel e no certificado.
- Anterior · Capítulo 18 de 21 · 35 minDecidir quando ampliar, corrigir ou encerrar o acervoVoltar para o capítulo 18
Leve uma ideia para a prática
Escolha uma atividade no painel e volte a este curso quando quiser.
Atividades e evolução ficam reunidas no painel da sua conta.
- 17Avaliar riscos de uso dos dados e de reputação
- 18Decidir quando ampliar, corrigir ou encerrar o acervo
- 19Apêndice: decidir quando as páginas são geradas
- 20Apêndice: apresentar endereços e atualizações ao buscador
- 21Apêndice: medir velocidade e capacidade da plataforma