Почему Hugo не загружает CSS-файл с хэшем на GitHub Pages и как это исправить

При сборке сайта на Hugo с темой Ananke и деплое на GitHub Pages вы можете столкнуться с ситуацией, когда сгенерированный CSS-файл в папке public/css/ получает имя с хэшем (например, _entry.b0a8f189.css), HTML-ссылка на него верна, сам файл присутствует в репозитории, но браузер выдаёт ошибку 404. Другие ресурсы (картинки, шрифты) загружаются нормально. Эта проблема часто связана с некорректной конфигурацией baseURL или особенностями работы assetBusting в Hugo. Ниже мы разберём основные причины и пошаговые решения.

Почему возникает ошибка 404 для CSS с хэшем

Hugo добавляет хэш к именам CSS-файлов для кэширования (cache busting). Когда сайт размещается на GitHub Pages, важно, чтобы baseURL был указан точно, включая слеш в конце. Если baseURL не совпадает с фактическим адресом, браузер ищет CSS по неправильному пути. Кроме того, необходимо убедиться, что файлы с хэшем корректно публикуются в корневой каталог репозитория (если используется ветка gh-pages или папка docs).

Пошаговая проверка и исправление

1. Корректный baseURL в конфигурации Hugo

Откройте файл config.yaml (или config.toml) вашего Hugo-сайта. Убедитесь, что параметр baseURL установлен в точный URL вашего GitHub Pages, например: baseURL: 'https://ponomarevava0.github.io/'. Обратите внимание на слеш в конце - он обязателен. Если ваш сайт расположен в подпапке (например, https://username.github.io/repository/), укажите полный путь со слешем.

2. Отключение assetBusting для отладки

Если проблема сохраняется, временно отключите генерацию хэшей. В config.yaml добавьте строку: disableAssetsBusting: true. После этого пересоберите сайт (hugo --cleanDestinationDir). Если CSS начнёт загружаться без хэша, значит, дело в кэшировании или несовместимости с GitHub Pages. Затем можно вернуть настройку обратно и искать точную причину.

3. Проверка структуры публикуемых файлов

Убедитесь, что папка public (или docs) содержит файл css/_entry.b0a8f189.css по правильному пути. Откройте репозиторий на GitHub и проверьте, что файл лежит именно там, где ожидает HTML. Иногда Hugo может помещать CSS в подпапку public/css/, а GitHub Pages ожидает его в корне. В таком случае настройте publishDir в конфиге.

4. Очистка кэша и пересборка

Удалите папку public вручную, затем выполните команду hugo --cleanDestinationDir для полной пересборки. После этого закоммитьте и запушьте изменения. Используйте git push -f только если уверены, что это не повредит историю. Очистите кэш браузера (Ctrl+F5) или откройте сайт в режиме инкогнито.

Альтернативные решения и лучшие практики

Если ни один из шагов не помог, попробуйте следующие подходы:

• Используйте подпапку docs вместо ветки gh-pages. В настройках репозитория GitHub выберите Source: main branch /docs folder. Убедитесь, что Hugo собирает сайт именно в ./docs (пропишите publishDir: docs в конфиге).
• Настройте GitHub Actions для автоматического деплоя. Это гарантирует, что все файлы будут опубликованы в правильной структуре. Пример workflow можно найти в документации Hugo.
• Проверьте .gitignore. Убедитесь, что папка public или docs не исключена из коммита. Если она в .gitignore, файлы не попадут в репозиторий.
• Протестируйте локально. Запустите hugo server и проверьте, загружается ли CSS локально. Если локально всё работает, проблема точно в конфигурации GitHub Pages.

Часто задаваемые вопросы

Мы собрали типичные вопросы пользователей, которые сталкиваются с ошибкой 404 CSS на GitHub Pages при использовании Hugo.