Next.js SEO
Como configurar a Metadata API do Next.js: títulos, URLs canônicas e Open Graph
Use a Metadata API do Next.js 16 para templates de título, URLs canônicas, metadados dinâmicos, cartões Open Graph e páginas App Router baseadas em dados.
Metadados ficam confiáveis quando vêm dos mesmos dados de rota e regras de URL da página visível. Duplicar essa lógica em outro sistema cliente cria divergências.
Usar metadados como dados de rota
Título, descrição, URL canônica e imagem social descrevem um recurso específico. Gere-os junto da rota responsável pelo recurso. O layout raiz fornece padrões estáveis do site; layouts aninhados definem convenções de seção; páginas controlam os valores específicos de cada entidade.
Essa hierarquia reduz repetições e torna o título final previsível. Também impede que um componente cliente passe a controlar os metadados após a primeira resposta. Exportações de metadados funcionam em Server Components, o limite adequado para dados privados e decisões de URL canônica.
Definir bons padrões no layout raiz
Defina metadataBase para a origem de produção e use caminhos relativos para URLs canônicas e imagens. Defina um template de título uma vez, para que as páginas filhas forneçam apenas a parte relevante. Os padrões devem ser corretos para as rotas que não os substituem, não textos genéricos copiados em todas as páginas.
Mantenha o nome do site consistente em títulos, cartões sociais e dados estruturados. Se staging e produção precisam de origens públicas diferentes, obtenha a origem permitida da configuração de implantação e falhe claramente se ela faltar, em vez de emitir URLs localhost silenciosamente.
export const metadata = {
metadataBase: new URL(process.env.NEXT_PUBLIC_SITE_URL),
title: {
default: "Northstar",
template: "%s | Northstar",
},
openGraph: {
siteName: "Northstar",
type: "website",
},
};Gerar metadados para rotas dinâmicas
generateMetadata recebe parâmetros assíncronos nas rotas dos projetos App Router atuais. Busque a entidade, retorne um título explícito de recurso não encontrado se ela não existir e monte a URL canônica a partir do slug durável. Não use o nome de exibição diretamente na URL, a menos que as mesmas regras de geração de slug tenham criado a rota.
Página e metadados costumam precisar do mesmo registro. Envolva a função de dados com React cache para deduplicá-la em uma renderização ou use cache persistente adequado ao ciclo de vida do conteúdo. O objetivo é uma fonte de verdade, não duas chamadas independentes de API que possam divergir.
import { cache } from "react";
const getPost = cache(async (slug: string) => {
return db.post.findUnique({ where: { slug, published: true } });
});
export async function generateMetadata({ params }) {
const { slug } = await params;
const post = await getPost(slug);
if (!post) return { title: "Article not found" };
return {
title: post.title,
description: post.excerpt,
alternates: { canonical: "/blog/" + post.slug },
};
}Escreva regras canônicas antes do código
Defina o uso de www, o comportamento da barra final, o locale de cada página e se filtros criam recursos distintos. Depois alinhe redirecionamentos, links internos, sitemap e metadados. Montar a URL canônica de forma improvisada em cada página acaba criando divergências.
Quando um slug mudar, redirecione a URL antiga para a nova canônica e preserve um identificador durável no banco. Para conteúdo excluído, verifique se há um substituto relacionado; caso contrário, retorne 404 ou 410 real, não uma página soft 404 com status de sucesso.
- —Uma origem e um protocolo preferidos.
- —Uma política de barra final.
- —Versões alternativas explícitas de locale quando as páginas traduzidas realmente existem.
- —Um plano de redirecionamento para slugs alterados e conteúdo desativado.
Tratar robots e entidades ausentes no servidor
Um rascunho, registro privado ou página interna de busca não deve se tornar indexável só porque o navegador o oculta depois. Retorne do servidor os metadados e o status corretos. Se a entidade não for pública, não exponha título ou descrição nos metadados antes de verificar a autorização.
Metadados robots não controlam acesso. Rotas privadas ainda exigem autenticação e autorização. Para links públicos de prévia, use identificadores impossíveis de adivinhar, noindex e regras claras de ciclo de vida. Mantenha as prévias fora do sitemap e da navegação interna.
Testar o documento renderizado
Inspecione o head do documento no navegador, mas também busque a resposta bruta e examine o código-fonte da página. Confirme título final, descrição, URL canônica, diretiva robots, valores Open Graph e JSON-LD em uma requisição direta. Teste uma entidade conhecida, uma ausente, um rascunho e um slug alterado.
Automatize as partes estáveis. Um teste básico da rota pode verificar status, URL canônica, trecho do título e ausência de origens de prévia. Mantenha humana a revisão da qualidade: um teste comprova que existe uma descrição, não que ela é útil.
Verificar metadados antes da promoção do domínio
Implante a candidata em uma rota HTTPS gerada pela Adios e inspecione a saída head da compilação de produção. Mantenha a origem pública do site em uma configuração revisável e valores sensíveis de provedores em referências a segredos. Os logs de compilação e execução ficam associados à candidata se a geração de metadados falhar.
Quando a versão responder com sucesso e seus metadados estiverem corretos, conecte ou mantenha o domínio personalizado canônico. TLS gerenciado e promoção de versões vinculam o host público à versão aprovada sem exigir mudanças DNS a cada publicação de conteúdo.
env:
NEXT_PUBLIC_SITE_URL: https://www.example.com
runtime:
name: node@24
port: 3000
health_path: /api/health