Hugo на сервере: частые ошибки и решения

MAATRIX

Hugo быстрый и надёжный, но при сборке и публикации статического сайта всплывают типичные ошибки: сборка падает на SCSS без extended-версии, ссылки и стили ведут не туда из-за неверного baseURL, сайт получается пустым, Nginx отдаёт 404, а после обновления ломается тема. Практически все частые ошибки Hugo объясняются понятными причинами — версия Hugo, конфиг, черновики, настройка Nginx, совместимость темы — и решаются проверенным набором действий. Разберём их по порядку, начиная с самых частых, с командами и пояснениями. Важно понимать, что у Hugo два разных класса проблем: ошибки сборки (когда команда hugo падает или собирает не то) и ошибки отдачи (когда собранный сайт неправильно показывается через Nginx). Диагностика у них разная. Ошибки сборки Hugo подробно печатает прямо в консоль с указанием файла и строки шаблона — читайте вывод команды. Ошибки отдачи ищут в логах Nginx (/var/log/nginx/error.log) и в конфиге виртуального хоста. Определив класс проблемы, вы сразу понимаете, где копать, и не тратите время впустую.

Сборка падает с ошибкой SCSS

Частая ошибка при сборке темы: this feature is not available in your current Hugo version или упоминание SCSS/Sass/toCSS. Причина в том, что установлена обычная версия Hugo, а тема использует SCSS, который умеет обрабатывать только расширенная (extended) сборка. Проверьте версию:

hugo version

Если в выводе нет пометки +extended, установите расширенную версию с официальных релизов вместо обычной. Скачайте пакет с hugo_extended в имени и переустановите. После этого сборка SCSS-темы пройдёт. Это самая распространённая причина, по которой чужая тема «не собирается» на свежем сервере, — всегда ставьте extended-версию, она универсальна и покрывает оба случая.

Битые ссылки, стили и картинки из-за baseURL

Сайт собрался, но открывается «сломанным»: не подгружаются стили, картинки битые, ссылки ведут на localhost или не туда. Почти всегда виноват неверный baseURL в конфиге. Hugo подставляет базовый адрес во все абсолютные ссылки при сборке, поэтому он должен точно соответствовать реальному адресу сайта. Откройте hugo.toml (или config.toml) и задайте корректное значение:

baseURL = 'https://vashdomen.ru/'

Обратите внимание на протокол (после выпуска SSL — обязательно https) и завершающий слэш. После изменения пересоберите сайт:

hugo --minify

Если сайт отдаётся из подкаталога, baseURL должен включать этот путь. Неверный протокол (http вместо https) вдобавок вызывает предупреждения о смешанном контенте в браузере. Правильный baseURL решает большинство проблем с «поехавшей» вёрсткой статического сайта.

Сайт получился пустым или без статей

После сборки сайт открывается, но статей нет, страницы пустые. Самая частая причина — контент помечен как черновик. Hugo по умолчанию не публикует файлы с draft: true в шапке. Откройте свои Markdown-файлы и уберите или замените эту строку на draft: false, затем пересоберите. Проверить, что именно попадёт в сборку, можно, собрав с включением черновиков для отладки:

hugo --buildDrafts

Если с этим флагом статьи появляются — дело именно в черновиках. Вторая причина пустого сайта — контент лежит не в том каталоге: статьи должны быть в content, а тема должна уметь их выводить. Третья — дата публикации в будущем: Hugo не публикует записи с будущей датой без флага --buildFuture. Проверьте поле date в шапке статьи.

Nginx отдаёт 404 или стандартную страницу

Сайт собран в public, но Nginx показывает 404 или свою приветственную страницу вместо вашего сайта. Причина в конфиге Nginx. Проверьте, что root в виртуальном хосте указывает именно на каталог public собранного сайта, а не на корень проекта:

root /var/www/vashdomen.ru/public;

Убедитесь, что конфиг активирован (симлинк в sites-enabled), нет конфликта с дефолтным сайтом Nginx (при необходимости удалите симлинк default), и проверьте синтаксис:

nginx -t && systemctl reload nginx

Если Nginx показывает свою страницу по умолчанию, значит запрос не попадает в ваш виртуальный хост — проверьте server_name (должен содержать ваш домен) и что домен резолвится на сервер. Ошибка 404 на отдельных страницах при работающей главной обычно означает, что сайт не пересобран после добавления контента, — выполните hugo --minify.

После обновления Hugo или темы ломается сборка

Обновили Hugo или тему, и сборка стала падать с ошибками в шаблонах. Причина — изменения синтаксиса: Hugo развивается быстро, и изредка устаревшие конструкции в шаблонах темы перестают работать в новой версии. Читайте вывод сборки: Hugo указывает конкретный файл шаблона и строку с проблемой. Варианты решения: обновить тему до версии, совместимой с новым Hugo (для подмодулей — git submodule update --remote), либо временно откатиться на предыдущую версию Hugo, если тема давно не обновлялась.

Чтобы такие сюрпризы не ломали боевой сайт, возьмите за правило проверять сборку после каждого обновления Hugo или темы на копии, прежде чем деплоить. Храните исходники в git — тогда откат к рабочему состоянию делается одной командой. Для заброшенных тем без поддержки новых версий Hugo разумно либо зафиксировать рабочую версию генератора, либо перейти на поддерживаемую тему.

Проблемы деплоя и обновления контента

Частая ситуация: правки контента не появляются на сайте. Причина проста и почти всегда одна — сайт не пересобран. Статика Hugo не обновляется сама: после любой правки Markdown нужно выполнить hugo --minify, чтобы каталог public обновился. Если вы автоматизировали деплой скриптом, проверьте, что он реально отрабатывает:

cd /var/www/vashdomen.ru && git pull && hugo --minify

Убедитесь, что git pull подтягивает изменения (нет конфликтов, верная ветка), а hugo завершается без ошибок. Ещё одна причина «старого» сайта — кэширование на стороне браузера или CDN: сделайте жёсткое обновление страницы или сбросьте кэш CDN. Проверьте также права: каталог public и исходники должны быть доступны пользователю, от которого идёт сборка и отдача. Правильно настроенный скрипт деплоя избавляет от ручной пересборки и связанных с ней забываний.

Частые вопросы