Netlify: как настроить перенаправления и исправить ошибку 404

О чём эта статья

• Проблема: при открытии генерируемого Netlify домена отображается 404 вместо домашней страницы.
• Решение: добавить правило перенаправления для SPA/статичных сайтов.
• Документы: примеры для _redirects, netlify.toml и настройки Angular.

Важно: краткая подсказка — правило должно вернуть статус 200 для всех путей и отдавать index.html.

Когда возникает ошибка и почему

Netlify автоматически развёртывает сайт из репозитория и назначает ему домен вида your-site-12345.netlify.app. Если сайт — одностраничное приложение (SPA) или генератор статических страниц с маршрутизацией на клиенте, то при открытии пути отличного от корня (например /about) сервер Netlify пытается найти файл /about и возвращает 404. Чтобы браузер получил ваш SPA и клиентская маршрутизация смогла отобразить нужную страницу, нужно перенаправлять все запросы на index.html с ответом 200.

Частые причины:

• Нет правил перенаправления для SPA.
• Файл _redirects находится не в директории publish.
• Для Angular: _redirects не включён в assets и не копируется в выходную папку.

Быстрый рецепт решения

1. В корне публикуемой директории (publish directory) создайте файл _redirects или netlify.toml.
2. Добавьте правило, перенаправляющее все запросы на index.html с кодом 200.
3. Убедитесь, что файл попадает в билд (для Angular добавьте его в assets).
4. Запушьте изменения и задеплойте заново.

Вариант 1 — файл _redirects

Файл _redirects простой и удобный, если вы не используете дополнительные правила или условия.

Порядок действий:

1. Откройте папку, которую вы указываете как “publish directory” (например, в React это обычно папка build или public/).
2. Создайте файл с именем _redirects (без расширения).
3. Добавьте в него правило:

/*    /index.html    200

Примечания:

• Первое поле — паттерн запроса.
• Второе — путь, на который делать fallback.
• Третье — HTTP-статус, 200 означает успешную отдачу страницы, важен для SPA.

Angular: чтобы файл копировался в сборку

Если проект на Angular, файл _redirects должен попасть в итоговый dist. Добавьте его в массив assets в angular.json (пример):

{
  "assets": [
    "src/favicon.ico",
    "src/assets",
    {
      "glob": "_redirects",
      "input": "src",
      "output": "/"
    }
  ]
}

После этого _redirects будет скопирован в корень сборки и Netlify сможет его обнаружить.

Вариант 2 — файл netlify.toml

Если вы предпочитаете конфиг в TOML и/или хотите хранить правила вместе с другими настройками Netlify, используйте netlify.toml.

Создайте в корне проекта или в publish директории файл netlify.toml и добавьте:

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

Преимущества netlify.toml:

• централизованный конфиг;
• поддержка сложных правил (условия, заголовки, proxy);
• можно хранить вместе с pipeline и остальными настройками.

Повторный деплой — шаги

1. Убедитесь, что publish directory в настройках сборки Netlify указывает на ту же папку, куда попал _redirects или netlify.toml.
2. Закоммитьте и запушьте изменения в ваш репозиторий.
3. Netlify автоматически запустит новый билд. Если нет — на странице сайта нажмите Deploy Settings → Trigger Deploy → Deploy site.
4. Дождитесь завершения сборки и откройте URL.

Проверка и критерии приёмки

Критерии приёмки:

• При переходе на корневой домен сайт загружается и не возвращает 404.
• При прямом открытии вложенного пути (например /about, /products/123) сервер отдает index.html с HTTP 200.
• Файл _redirects или netlify.toml присутствует в publish директории после сборки.

Проверочные шаги (acceptance):

• Откройте DevTools → Network. Перейдите по URL /non-existing-path. В ответе должна прийти index.html и статус 200.

Когда это может не сработать

• Вы настраивали собственный прокси или заголовки ответа, которые переопределяют поведение Netlify.
• Файл _redirects не попал в ту директорию, которую Netlify использует как publish.
• В netlify.toml допущена синтаксическая ошибка — проверьте формат.
• Вы используете серверную сторону (SSR) и ожидаете от Netlify поведения полноценного сервера — Netlify в основном для статичных сайтов и функций Serverless.

Альтернативные подходы

• Настроить маршрутизацию на стороне клиента таким образом, чтобы при загрузке любого пути обрабатывался index.html (обычно стандарт для SPA).
• Для проектов с SSR рассмотреть хостинг, поддерживающий полноценные серверные рендеры (например Vercel, AWS, DigitalOcean App Platform).
• Использовать Netlify Functions для подстановки динамического ответа при сложной логике маршрутизации.

Шпаргалка и сниппеты

• Минимум для SPA в _redirects:

/*    /index.html    200

• Минимум для netlify.toml:

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

• Angular: добавьте _redirects в assets как показано выше.

Рабочий план для команды (role-based checklist)

Для разработчика фронтенда:

• Создать _redirects или netlify.toml в исходниках.
• Локально проверить сборку и убедиться, что файл копируется в папку билд.

Для инженера CI/CD:

• Проверить настройки publish directory в настройках Netlify.
• Убедиться, что в pipeline файлы не удаляются и копируются корректно.

Для продуктового менеджера:

• Прогнать основные пути вручную на staging-сайте.
• Убедиться, что SEO-боты получают 200 и индексируют сайт корректно.

Быстрая методология отладки (runbook)

1. Откройте сайт и подтвердите 404. Запишите путь, при котором возникает 404.
2. На Netlify в логах сборки проверьте, копировался ли _redirects или netlify.toml.
3. Если файла нет — добавьте его в исходники и запустите билд.
4. Если файл есть, просмотрите содержимое на предмет опечаток.
5. Проверьте publish directory в Build Settings.
6. Запустите повторный деплой и тесты.

Диаграмма принятия решения

flowchart TD
  A[Наблюдается 404] --> B{Файл _redirects или netlify.toml
  присутствует в сборке?}
  B -- Да --> C{Настройка publish directory
  корректна?}
  B -- Нет --> D[Добавить файл в исходники
  и включить в сборку]
  C -- Да --> E[Проверить правила и
  запустить повторный деплой]
  C -- Нет --> F[Исправить publish directory
  в Build Settings]
  D --> E
  F --> E
  E --> G[Открыть URL и проверить
  ответ 200 + index.html]

Частые ошибки и их решения

• Ошибка: Файл есть, но все равно 404 — возможно publish directory не совпадает с местом, куда билд складывает файлы. Проверьте Build Settings.
• Ошибка: netlify.toml не применяет правило — проверьте синтаксис TOML, и что файл находится в корне репозитория, который Netlify использует.

Короткая сводка и рекомендации

• Используйте _redirects для простых SPA-правил, netlify.toml — если нужен централизованный конфиг.
• Для Angular убедитесь, что _redirects копируется в dist через assets.
• Всегда проверяйте, что publish directory совпадает с тем, что указывает Netlify.

Заметки

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

FAQ

Почему Netlify отдает 404 вместо моей домашней страницы?

Потому что Netlify ищет файл, соответствующий запрошенному пути, и если его нет, возвращает 404. Для SPA нужно делать fallback на index.html.

Можно ли использовать netlify.toml и _redirects одновременно?

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

Краткое резюме

• Добавьте правило перенаправления (через _redirects или netlify.toml), чтобы направлять все запросы на index.html с кодом 200.
• Проверьте, что файл включён в publish directory и что Netlify использует правильную папку для публикации.
• Запустите повторный деплой и убедитесь, что запросы к вложенным путям возвращают index.html и статус 200.