Pagine di errore personalizzate Nginx: migliora l'esperienza utente

Le pagine di errore personalizzate di Nginx trasformano un fallimento grezzo in un chiaro passo successivo. Non risolvono il link rotto, il file mancante o l'app upstream crashata. Fanno qualcosa di più piccolo ma comunque prezioso: dicono al visitatore cosa è successo in linguaggio semplice e gli impediscono di sentirsi abbandonato dal tuo sito.

Questo è importante durante errori ordinari. Qualcuno segue un vecchio link della documentazione e ottiene un 404. Un percorso di file privato restituisce 403. La tua app si riavvia durante il deployment e Nginx vede brevemente un 502. Senza una pagina personalizzata, gli utenti potrebbero vedere una risposta predefinita del server che appare brusca o tecnica. Con una buona pagina statica, sanno se cercare, tornare indietro, riprovare o aspettare.

Le migliori pagine di errore sono strumenti operativi noiosi. Sono statiche, veloci, accessibili e oneste. Non nascondono i guasti dal monitoraggio e non espongono dettagli interni agli utenti.

Inizia con gli errori che le persone vedono effettivamente

Non devi progettare una pagina per ogni codice di stato HTTP. Inizia con quelli comuni.

404 Non Trovato è la prima pagina da personalizzare. Appare quando l'URL richiesto non corrisponde a un file, una rotta o una posizione Nginx che restituisce contenuto. Vecchi link, post rinominati, pagine di documentazione cancellate e URL digitati a mano portano tutti qui.

Una pagina 404 utile dice qualcosa come: "Non abbiamo trovato quella pagina." Poi offre un percorso di ritorno alla homepage, all'indice della documentazione, all'area prodotto o alla pagina di ricerca. Non dare la colpa all'utente. L'URL potrebbe essere stato sbagliato molto prima che lo cliccassero.

403 Vietato è diverso. Nginx ha capito la richiesta ma non la servirà. Le cause includono permessi dei file, regole di accesso, elenco directory disabilitato, regole IP allow/deny o requisiti di autenticazione. Una pagina 403 dovrebbe essere calma e breve. Se la risorsa è privata, dillo. Se gli utenti potrebbero aver bisogno di accesso, indirizzali al login o al percorso di supporto corretto.

Per i siti basati su app, gestisci gli errori 50x con attenzione:

500 Errore Interno del Server di solito significa che l'applicazione è fallita durante l'elaborazione della richiesta.
502 Gateway Non Valido spesso significa che Nginx non ha ricevuto una risposta valida dal servizio upstream.
503 Servizio Non Disponibile è utile per manutenzione, sovraccarico o un servizio deliberatamente non disponibile.
504 Timeout del Gateway significa che Nginx ha aspettato troppo a lungo per la risposta upstream.

Un esempio di dashboard SaaS: il processo della tua app si riavvia durante il deployment. Per alcuni secondi, Nginx non può connettersi all'upstream e gli utenti vedono un 502. Una pagina personalizzata può dire: "La dashboard è temporaneamente non disponibile. Per favore, aggiorna tra un minuto." Non è perfetto, ma è più chiaro di un errore gateway predefinito.

Crea file di errore statici

Mantieni le pagine di errore al di fuori della catena di dipendenze dell'applicazione. Se il database è giù, la pagina 500 dovrebbe comunque caricarsi. Se l'app Node, Python, Ruby o PHP è malsana, Nginx dovrebbe comunque servire il fallback statico.

Una semplice struttura di file potrebbe essere:

/var/www/example.com/public/
  index.html
  assets/
/var/www/example.com/errors/
  404.html
  403.html
  50x.html

Mantieni l'HTML leggero. Evita script di terze parti, immagini pesanti, bundle di app lato client e qualsiasi cosa chiami il backend rotto. Un piccolo file CSS va bene se Nginx può servirlo direttamente.

Un 404.html minimo potrebbe essere:

<!doctype html>
<html lang="it">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Pagina non trovata</title>
</head>
<body>
  <main>
    <h1>Pagina non trovata</h1>
    <p>La pagina potrebbe essere stata spostata o il link potrebbe essere obsoleto.</p>
    <p><a href="/">Vai alla homepage</a></p>
  </main>
</body>
</html>

Questo è sufficiente. Puoi stilizzarlo per abbinarlo al tuo sito, ma il messaggio e i link contano più della decorazione.

Collega le pagine con `error_page`

In Nginx, la direttiva error_page mappa uno o più codici di stato a un URI. Un blocco server di base assomiglia a questo:

server {
    listen 80;
    server_name example.com www.example.com;

    root /var/www/example.com/public;

    error_page 404 /errors/404.html;
    error_page 403 /errors/403.html;
    error_page 500 502 503 504 /errors/50x.html;

    location /errors/ {
        internal;
        root /var/www/example.com;
    }

    location / {
        try_files $uri $uri/ =404;
    }
}

La risoluzione del percorso è la parte che confonde le persone. In questo esempio, le richieste sotto /errors/ usano root /var/www/example.com;, quindi /errors/404.html viene mappato a /var/www/example.com/errors/404.html.

La direttiva internal significa che i client esterni non possono richiedere /errors/404.html direttamente come URL normale. Nginx può comunque servirlo internamente quando gestisce un errore.

Dopo aver modificato la configurazione, testa e ricarica:

sudo nginx -t
sudo systemctl reload nginx

Poi testa il comportamento:

curl -I http://example.com/pagina-decisamente-mancante
curl -s http://example.com/pagina-decisamente-mancante | head

Lo stato dovrebbe ancora essere 404, anche se il corpo è il tuo HTML amichevole. Un errore comune è restituire accidentalmente 200 OK per una pagina mancante, il che fa pensare a monitoraggio e motori di ricerca che l'URL mancante sia una pagina reale.

Pagine personalizzate dietro un proxy inverso

Se Nginx fa da proxy a un'applicazione upstream, l'app potrebbe restituire le proprie risposte di errore. Per impostazione predefinita, le risposte proxy vengono solitamente passate al client. Per fare in modo che Nginx intercetti le risposte di errore upstream e usi le tue regole error_page, abilita proxy_intercept_errors nel contesto pertinente.

location /app/ {
    proxy_pass http://app_backend;
    proxy_intercept_errors on;

    error_page 502 503 504 /errors/50x.html;
}

La documentazione di Nginx descrive proxy_intercept_errors come applicabile a risposte proxy con codici di stato maggiori o uguali a 300, che possono poi essere reindirizzate a Nginx per l'elaborazione di error_page. In pratica, non attivarlo ovunque senza pensarci.

Per le pagine del browser, intercettare 502 o 503 è spesso utile. Per le API JSON, potrebbe essere sbagliato. I client API di solito si aspettano un corpo di errore JSON strutturato, non una pagina HTML. Potresti aver bisogno di posizioni separate:

location /api/ {
    proxy_pass http://api_backend;
    proxy_intercept_errors off;
}

location /dashboard/ {
    proxy_pass http://app_backend;
    proxy_intercept_errors on;
    error_page 502 503 504 /errors/50x.html;
}

Questa suddivisione mantiene le pagine per umani amichevoli preservando gli errori API leggibili dalla macchina.

Preserva il codice di stato corretto

Nginx ti permette di cambiare il codice di risposta con error_page, ma fallo solo quando lo intendi. Questa è sintassi valida:

error_page 404 =200 /fallback.html;

Per la maggior parte dei siti web, sarebbe una cattiva idea. Una pagina mancante dovrebbe rimanere un 404. Motori di ricerca, controlli di uptime, analytics e utenti beneficiano tutti della verità.

Ci sono casi legittimi per cambiare i codici, come instradare certi errori verso una posizione nominata o restituire una pagina di manutenzione con 503. Ma come regola predefinita, preserva lo stato di errore originale.

Per la manutenzione, puoi essere esplicito:

location / {
    return 503;
}

error_page 503 /errors/manutenzione.html;

location = /errors/manutenzione.html {
    root /var/www/example.com;
    internal;
}

Se usi un CDN o un bilanciatore di carico davanti a Nginx, ricorda che potrebbe avere il proprio comportamento per le pagine di errore. Decidi quale livello possiede quali errori. Altrimenti, potresti testare Nginx direttamente e vedere una pagina, mentre gli utenti dietro il CDN ne vedono un'altra.

Scrivi pagine di errore per umani

Il contenuto dovrebbe rispondere rapidamente a tre domande:

Cosa è successo?
È temporaneo?
Cosa posso fare dopo?

Per un 404, i passi successivi utili sono ricerca, homepage, indice della documentazione o contattare il supporto se la pagina mancante dovrebbe esistere. Per un 503, una guida utile è riprovare più tardi o controllare una pagina di stato. Per un 403, indirizza alle istruzioni di accesso o richiesta di accesso se appropriato.

Evita stack trace, nomi host upstream, percorsi del filesystem, versioni dei pacchetti, IP interni, ID di richiesta senza spiegazione e dettagli di incidenti. Un ID di richiesta può essere utile se il supporto può usarlo, ma etichettalo chiaramente:

<p>Se contatti il supporto, includi questo ID di richiesta: <code>$request_id</code></p>

Per iniettare variabili come $request_id, hai bisogno di un pattern di configurazione che lo supporti. I file HTML statici non espanderanno le variabili Nginx da soli. Molti team mantengono le pagine di errore pubbliche statiche e si affidano ai log per gli ID di richiesta.

L'accessibilità fa parte dell'utilità. Usa un h1 chiaro, contrasto leggibile, link normali e testo semplice. Non rendere l'unica azione di recupero una piccola icona o un pulsante basato su script.

Testa le pagine apposta

Non aspettare che gli utenti trovino le tue pagine di errore. Testale dopo ogni modifica.

Per 404:

curl -i https://example.com/nessuna-tale-pagina

Per 403, crea una posizione di test controllata o usa un file di test privato. Non allentare i permessi di produzione solo per innescare un errore.

Per 502 o 503, testa in staging puntando una posizione verso un upstream non disponibile:

location /test-upstream-rotto/ {
    proxy_pass http://127.0.0.1:59999;
    proxy_intercept_errors on;
    error_page 502 503 504 /errors/50x.html;
}

Poi richiedilo e conferma sia il codice di stato che il corpo:

curl -i https://staging.example.com/test-upstream-rotto/

Controlla anche i log:

sudo tail -f /var/log/nginx/error.log /var/log/nginx/access.log

Una bella pagina di errore non dovrebbe cancellare il segnale operativo. I tuoi avvisi dovrebbero ancora attivarsi quando i tassi di 50x aumentano.

Le pagine di errore personalizzate di Nginx sono un piccolo compito di configurazione con un impatto reale sull'utente. Inizia con 404, 403 e i comuni errori 50x. Servi file statici direttamente da Nginx. Preserva codici di stato accurati. Usa proxy_intercept_errors solo dove i fallback HTML hanno senso. Poi testa le pagine come faresti con qualsiasi altro comportamento di produzione.