Как использовать свои страницы ошибок

Как кастомизировать стандартные страницы ошибок

В процессе настройки нового веб‑сервера, вы можете захотеть чтобы страницы ошибок отображались в красивом виде, вместо стандартного. Также иногда страницы ошибок должны быть в том же оформлении, что и основной сайт и/или предоставлять пользователям какую‑то дополнительную информацию, такую как, например, контакты, альтернативные способы решения возникшей проблемы или что‑то иное.

Для упрощения процесса, я создал небольшую утилиту (прямая ссылка на проект в GitHub), по сути Node.js скрипт, которая позволяет создавать статические страницы ошибок в собственном дизайне и со своими текстовыми сообщениями. По умолчанию, утилита содержит только один шаблон в минималистичном дизайне (с поддержкой доступности и адаптивности, на сколько это возможно в такой простой странице). Но если вас не устраивает такой дизайн, то вы можете с легкостью изменить его, путем создания собственного: со своими стилями, шрифтами, изображениями и текстами.

Для возможности создания страниц на других языка, утилита позволяет использовать собственные языковые пакеты, включающие свои кастомные текстовые сообщения.

Для упрощения интеграции, утилита автоматически создает сниппет с конфигурацией веб сервера, который легко может быть добавлен в конфигурацию вашего веб сервера. На текущий момент сниппет создается только для Nginx. Другие виды серверов будут добавлены позже (в качестве альтернативы, вы можете создать Pull Request с таким улучшениями, либо оформить Feature Request).

Использование

В базовом сценарии использования, всё что требуется, это лишь склонировать себе на компьютер репозиторий проекта, установить зависимости Node.js, запустить команду сборки, скопировать полученный результат к себе на сервер и обновить конфигурацию сервера.

$ git clone git@github.com:sapachev/error-pages.git
…
$ npm install --production
…
$ npm run build
…
INFO: Start building process
INFO: Flush build directory '/home/error-pages/dist'
INFO: Compile pages from source data:
 • /home/error-pages/dist/400.html
 • /home/error-pages/dist/401.html
 • /home/error-pages/dist/403.html
 • /home/error-pages/dist/404.html
 • /home/error-pages/dist/410.html
 • /home/error-pages/dist/500.html
 • /home/error-pages/dist/502.html
 • /home/error-pages/dist/503.html
 • /home/error-pages/dist/504.html
INFO: Compile web servers config snippets from source data:
 • /home/error-pages/dist/nginx-error-pages.conf
INFO: Build Tailwind CSS styles
INFO: Run 'INPUT="/home/error-pages/themes/minimalistic/@assets/css/main.twnd.css" OUTPUT="/home/error-pages/dist/@assets/css/main.css" npm run build:tailwind' command
INFO: Tailwind CSS styles were built
INFO: Copying assets to '/home/error-pages/dist/@assets' directory
INFO: Building process was completed in 1.727s

Продвинутое использование

В дополнение к шагам базового сценария, вы можете улучшить скомпилированные страницы меняя части, из которых они собираются: шаблоны, стили, тексты, а также сниппеты конфигурации.

Основная конфигурация утилиты хранится в файле config.json в корневой папке, которую можно менять в соответствии со своими требованиями:

{
  "tailwind": true,
  "theme": "minimalistic",
  "locale": "en"
}

Шаблоны

Все шаблоны хранятся в папке themes, где стандартной темой является minimalistic, которую можно изменить или добавить новую. Каких‑то особых требований к шаблонам страниц нет: каждый шаблон является обыкновенным HTML документом, с внедренными переменными, на месте которых будут текстовки из файлов локализации. Для обработки внедренных переменных используется библиотека mustache.js. Таким образом, если нужно реализовать какую‑то особенную логику в своих шаблонах, то вы можете ознакомиться с документацией этой библиотеки для определения имеющихся возможностей шаблонизации.

После добавления своего шаблона, просто укажите его в файле конфигурации, чтобы скомпилировать страницы с его использованием.

Стили

Стилизация шаблонов базируется на фреймворке Tailwind CSS. С помощью этого фреймворка, можно быстро описывать стили страниц без необходимости писать отдельный CSS код. Точкой входа для стилей Tailwind должен быть файл themes/<name>/@assets/css/main.twnd.css. Из него в дальнейшем будет создан файл main.css, который содержит скомпилированные и минифицированные стили. В дополнение, можно настроить Tailwind с помощью создания кастомной конфигурации, расположенной в файле theme.tailwind.config.js в корне папки с темой, и описать в ней любые опции Tailwind. Полный список опций Tailwind доступен в документации самого Tailwind.

Однако, если по каким-то причинам использование Tailwind не требуется (например, стили уже описаны ранее в CSS), компиляцию стилей Tailwind можно отключить в основной конфигурации утилиты (файл config.json). В этом случае шаг сборки стилей будет просто пропущен без какого-либо влияния на финальный результат.

Текстовые сообщения и Локализация

Все текстовые сообщения хранятся в JSON файлах, разделенных по признаку языка, и расположены в папке src. Каждая страница создается из соответствующего ей файла локализации вида <Код HTTP>.json (<Код HTTP> – это число, соответствующее коду ошибки HTTP). Таким образом, если нужно создать страницу для кода, который еще не описан, то просто создайте соответствующий JSON файл, содержащий описание этого статуса в соответствующих свойствах.

Любой файл локализации может быть расширен любым количеством дополнительных свойств, которые вам нужно отобразить на странице. Для определения общих свойств, вы можете использовать файл common.json – свойства из этого файла будут применены к каждой странице.

Для локализации страниц, просто создайте новую папку в директории src, содержащую JSON файлы с текстами страниц. Создавая JSON файлы, вы можете описать любой набор HTTP кодов (например, только для 400-ых ошибок) – просто следуйте конвенции именования, и не забывайте выделять общие тексты в файл common.json.

Конфигурации сервера

В процессе работы, Утилита автоматически создаст сниппет для вашего сервера, который будет содержать лишь те страницы, которые были созданы. Данный сниппет будет содержать настройки обрабатываемых ошибок, и указывать на страницы, которые будут их представлять. Как было сказано ранее, на данный момент только Nginx поддерживается.

Для использования полученных страниц, остается только скопировать на сервер все файлы из папки dist и включить использование сниппета в уже существующей конфигурации сервера. В соответствии с шаблоном сниппета, все страницы должны быть расположены в папке /usr/share/nginx/html/error-pages. В случае если настройки в снипетта не подходят, то вы можете отредактировать шаблон сниппета в папке snippets. Так же как и для тем оформления, шаблоны конфигураций поддерживают mustache.js, тем позволяя реализовать в шаблоне любую логику (списки, условия и т. д.).

Сам по себе конфиг, я рекомендую располагать в папке /etc/nginx/snippets/, а для его подключения использовать строчку конфигурации: include /etc/nginx/snippets/nginx-error-pages.conf;. Разумеется, это не более чем рекомендация, т.к. в реальности всё может быть иначе или сложнее.

Ниже приведен простой пример конфигурации веб‑сервера с включенным в нее сниппетом кастомных ошибок:

server {
    server_name example.com;
    access_log /var/log/nginx/example.access.log;

    include /etc/nginx/snippets/nginx-error-pages.conf;

    location / {
        root /data/www;
    }
}

Демо

Посмотреть как выглядят страницы ошибок можно на моем сайте по следующим ссылкам:

• 400 Bad Request

• 401 Unauthorized

• 403 Forbidden

• 404 Not Found

• 410 Gone

• 500 Internal Server Error

• 502 Bad Gateway

• 503 Service Unavailable

• 504 Gateway Timeout

Сообщение об ошибках и запрос новых функций

Код утилиты нельзя назвать каким‑то сложным, однако, несмотря на этот факт, все значимые части покрыты юнит‑тестами. Впрочем, это не является гарантией отсутствия каких‑либо ошибок, поэтому если вы столкнетесь с какими‑то проблемами, то, пожалуйста, сообщите мне о них, через создание Issue в репозитории проекта: https://github.com/sapachev/error‑pages/issues

Также приветствуется создание запросов новых функций, которые вы хотели бы увидеть в данной утилите.

Участие в разработке

Проект открыт для всех желающих, и если у вас есть идеи, а главное желание и возможности их реализовать, то с радостью рассмотрю их в виде Pull Request. Со своей стороны готов предоставить вам поддержку в реализации вашей задумки. Не стесняйтесь спрашивать меня о коде, и возможных решениях вашей идеи.

От автора: в этом уроке мы с вами познакомимся еще с двумя полезными директивами сервера, которые можно использовать в файле htaccess.

Первая директива используется довольно редко, но иногда она может быть попросту незаменима. Вторую же директиву можно и нужно использовать практически в любом Вашем проекте.

Иногда на сайте, написанном исключительно на HTML, может возникнуть необходимость вставки кода PHP. Но, как Вы знаете, файлы с расширением html сервер сразу же отдает клиенту и программный код в этих файлах никак не обрабатывается.

Другое дело файлы php. Здесь правильно настроенный сервер ни за что не отдаст просто так такой файл. Прежде всего, сервер отдает этот файл интерпретатору PHP, который, в свою очередь, обрабатывает файл, выполняя программный код в файле. Затем интерпретатор возвращает уже обработанный документ серверу, который отдает его уже клиенту.

Как же нам «заставить» сервер отдавать, к примеру, файлы html интерпретатору для исполнения программного кода? В этом нам как раз и поможет следующая директива:

Как Вы заметили, через пробел мы можем перечислять и любые другие расширения файлов, которые сервер должен пропускать через интерпретатор.

Вторая директива очень полезна и помогает отдавать так называемые собственные страницы ошибок.

Когда сервер в результате запроса клиента генерирует ошибку, то эту ошибку он показывает клиенту на специальной странице. Например, это может быть ошибка 404 (файл не найден), ошибка 403 (доступ запрещен), ошибка 500 (внутренняя ошибка сервера) и много других.

Как уже отмечалось, сервер сообщает клиенту об ошибке, генерируя собственную страницу ошибки. Чаще всего это обычная белая страничка с непритязательной надписью.

Специалисты советуют не оставлять дефолтные страницы ошибок и заменять их на собственные – это могут быть страницы, выполненные в дизайне сайта, или имеющие собственный дизайн. Главное, чтобы страница была информативной и, попав на нее, клиент сразу же понял, что он, к примеру, ошибся в адресе при наборе страницы и т.д.

Указать серверу на собственные страницы ошибок можно с помощью директивы ErrorDocument, после которой мы укажем код ошибки и путь к странице ошибки, которую нужно показать в случае данной ошибки:

Здесь, как Вы могли заметить, мы можем использовать как относительный, так и абсолютный путь. Также, как вариант, можно вместо страницы показать какой-нибудь текст (хотя в этом мало смысла).

На этом текущий урок завершен. Удачи и до встречи в следующем!

Перейти к содержанию

<html>
<head>
<title>My Custom 404 Error Page</title>
</head>

<body>
<p>Whoops, page not found! Sorry about that.</p>

</body>
</html>

ErrorDocument 404 [path to file]

ErrorDocument 404 /my-404.html

<VirtualHost *:80>
ServerName example.com
    <Directory "/var/www/example.com/html">
    AllowOverride All
    </Directory>
</VirtualHost>

<VirtualHost *:80>
ServerName example.com
ErrorDocument 404 /my-404.html
    <Directory "/var/www/example.com/html">
    AllowOverride All
    </Directory>
</VirtualHost>