Come configurare la Metadata API di Next.js: titoli, URL canonici e Open Graph

Usa la Metadata API di Next.js 16 per modelli di titolo, URL canonici, metadati dinamici, schede Open Graph e pagine App Router basate sui dati.

Team di Adios16 luglio 2026Aggiornato 17 luglio 20269 min di lettura

I metadati diventano affidabili quando derivano dagli stessi dati della route e dalle stesse regole degli URL della pagina visibile. Duplicare quella logica in un secondo sistema lato client crea divergenze.

Usa i metadati come dati della route

Titolo della pagina, descrizione, URL canonico e immagine di condivisione descrivono una risorsa specifica. Generali accanto alla route che la gestisce. Il layout radice deve fornire impostazioni stabili del sito, i layout annidati possono definire convenzioni delle sezioni e le pagine devono gestire i valori specifici dell'entità.

Questa gerarchia riduce le ripetizioni e rende prevedibile il titolo finale. Impedisce inoltre che un componente client diventi responsabile dei metadati del documento dopo la prima risposta. Le esportazioni dei metadati funzionano nei Server Components, il confine corretto per l'accesso ai dati privati e le decisioni sugli URL canonici.

Definisci solide impostazioni predefinite nel layout radice

Imposta metadataBase sull'origine di produzione, poi usa percorsi relativi per URL canonici e immagini. Definisci un modello di titolo una sola volta, così le pagine figlie forniscono solo la parte significativa. Le impostazioni predefinite devono essere accurate per le route che non le sostituiscono, senza diventare riempitivi copiati su ogni pagina.

Mantieni stabile il nome del sito tra titoli, schede di condivisione e dati strutturati. Se staging e produzione richiedono origini pubbliche diverse, risolvi l'origine ammessa dalla configurazione di distribuzione e segnala chiaramente l'errore quando manca, senza generare silenziosamente URL localhost.

export const metadata = {
  metadataBase: new URL(process.env.NEXT_PUBLIC_SITE_URL),
  title: {
    default: "Northstar",
    template: "%s | Northstar",
  },
  openGraph: {
    siteName: "Northstar",
    type: "website",
  },
};

Genera metadati per route dinamiche

generateMetadata riceve parametri di route asincroni nei progetti App Router attuali. Recupera l'entità, restituisci un titolo esplicito di contenuto non trovato se manca e costruisci l'URL canonico dal suo slug stabile. Non usare un nome visualizzato direttamente nell'URL, salvo che le stesse regole di generazione degli slug abbiano creato la route.

Pagina e metadati richiedono spesso lo stesso record. Avvolgi la funzione dati con React cache per deduplicarla durante un singolo rendering oppure usa una cache persistente adatta quando il ciclo di vita dei contenuti lo richiede. L'obiettivo è un'unica fonte ufficiale, non due chiamate API indipendenti che possono divergere.

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 },
  };
}

Scrivi le regole canoniche prima del codice

Decidi se il sito usa www, come gestisce le barre finali, quale versione linguistica corrisponde a una pagina e se i parametri dei filtri creano risorse distinte. Allinea poi reindirizzamenti, link interni, URL delle sitemap e metadati. Un URL canonico costruito separatamente in ogni pagina finirà per divergere.

Quando lo slug di un contenuto cambia, reindirizza il vecchio URL al nuovo URL canonico e conserva un identificatore stabile nel database. Per contenuti eliminati, valuta se esiste un sostituto pertinente; altrimenti restituisci un vero 404 o 410, anziché una pagina soft 404 con stato di successo.

—Un'unica origine e un unico protocollo preferiti.
—Un'unica politica sulla barra finale.
—Versioni linguistiche alternative esplicite dove esistono davvero pagine tradotte.
—Un piano di reindirizzamento per slug modificati e contenuti dismessi.

Crea schede di condivisione coerenti con la pagina

I campi Open Graph e Twitter devono usare titolo della pagina, descrizione concisa e un'immagine leggibile anche se ritagliata. Un'immagine generica del sito è un fallback accettabile, ma articoli e prodotti beneficiano di schede specifiche dell'entità. Fornisci dimensioni e testo alt significativo.

Le immagini statiche possono usare la convenzione di file opengraph-image. Le route dinamiche possono generare un'immagine con ImageResponse o richiamarne una salvata con l'entità. Tratta la generazione delle immagini come codice di produzione: verifica titoli lunghi, immagini mancanti, caricamento dei font e costi dell'ambiente di esecuzione.

return {
  openGraph: {
    type: "article",
    title: post.title,
    description: post.excerpt,
    images: [{
      url: post.ogImage,
      width: 1200,
      height: 630,
      alt: post.title,
    }],
  },
};

Gestisci robots ed entità mancanti sul server

Una bozza, un record privato o una pagina di ricerca interna non deve diventare indicizzabile solo perché il browser la nasconde in seguito. Restituisci metadati e stato corretti dal server. Se un'entità non è pubblica, non esporne titolo o descrizione nei metadati prima della verifica dell'autorizzazione.

I metadati robots non controllano l'accesso. Le route private richiedono comunque autenticazione e autorizzazione. Per link pubblici di anteprima, usa identificatori non indovinabili, metadati noindex e regole chiare del ciclo di vita; assicurati poi che le anteprime siano assenti da sitemap e navigazione interna.

Verifica il documento renderizzato

Esamina head del documento nel browser, ma recupera anche la risposta originale e visualizza il sorgente della pagina. Conferma che titolo finale, descrizione, URL canonico, direttiva robots, valori Open Graph e JSON-LD siano corretti per una richiesta diretta. Verifica un'entità nota, una mancante, una bozza e uno slug modificato.

Automatizza le parti stabili. Uno smoke test della route può verificare stato, URL canonico, parte del titolo e assenza di origini di anteprima. Lascia alle persone la revisione della qualità dei contenuti: un test può dimostrare che una descrizione esiste, ma non che sia utile.

Verifica i metadati prima della promozione sul dominio

Distribuisci la candidata su una route HTTPS generata da Adios ed esamina il contenuto head con la compilazione di produzione. Mantieni l'origine pubblica del sito in una configurazione esaminabile e i valori sensibili dei provider dietro riferimenti ai segreti. I log della compilazione e dell'ambiente di esecuzione rimangono associati alla candidata se la generazione dei metadati fallisce.

Quando il rilascio risponde correttamente e i metadati sono giusti, collega o mantieni il dominio personalizzato canonico. TLS gestito e promozione dei rilasci mantengono l'hostname pubblico associato alla versione verificata, senza richiedere modifiche DNS a ogni rilascio di contenuti.

env:
  NEXT_PUBLIC_SITE_URL: https://www.example.com

runtime:
  name: node@24
  port: 3000
  health_path: /api/health

Tutti gli articoli