Nginx: кастомные страницы ошибок (error_page)

Настройка кастомных страниц ошибок в nginx через директиву error_page. Поддержка внутренних и внешних редиректов.

Базовый пример

server {
    listen 80;
    server_name example.com;
    root /var/www/html;

    # Кастомная страница 404
    error_page 404 /404.html;
    
    # Кастомная страница 500
    error_page 500 502 503 /50x.html;

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

    # Внутренний location для страницы ошибки
    location = /404.html {
        internal;
        root /var/www/html;
    }

    location = /50x.html {
        internal;
        root /var/www/html;
    }
}

Внешний редирект на страницу ошибки

server {
    listen 80;
    server_name example.com;

    # Внешний редирект (браузер получит новый URL)
    error_page 404 https://example.com/custom-404;
    error_page 500 502 503 https://example.com/error;
}

Внутренний редирект с изменением кода ответа

server {
    listen 80;
    server_name example.com;
    root /var/www/html;

    # Внутренний редирект, но возвращаем код 200 вместо 404
    error_page 404 =200 /index.html;

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

Обработка ошибок проксирования

server {
    listen 80;
    server_name example.com;

    location /api/ {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        
        # Обработка ошибок от backend
        error_page 502 503 504 /50x.html;
    }

    location = /50x.html {
        internal;
        root /var/www/html;
    }
}

Полный пример с разными кодами ошибок

server {
    listen 80;
    server_name example.com;
    root /var/www/html;

    # Разные страницы для разных ошибок
    error_page 404 /404.html;
    error_page 403 /403.html;
    error_page 500 502 503 504 /50x.html;

    # Внутренние location для страниц ошибок
    location = /404.html {
        internal;
        expires -1;
        add_header Cache-Control "no-cache";
    }

    location = /403.html {
        internal;
        expires -1;
    }

    location = /50x.html {
        internal;
        expires -1;
    }

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

Usage:

Добавьте error_page в server block. Используйте internal для внутренних location, чтобы страницы ошибок не были доступны напрямую по URL.

Notes:

⚠️ internal означает, что location доступен только для внутренних редиректов nginx. Без internal страница ошибки будет доступна по прямому URL. =200 в error_page 404 =200 /index.html меняет код ответа на 200 (полезно для SPA).