Исправление перенаправлений Netlify

Netlify — популярная платформа для хостинга статических сайтов и одностраничных приложений (SPA). Она интегрируется с Git-хостингом (GitHub, Bitbucket и др.) и разворачивает сайт из вашего репозитория.

Иногда после первого деплоя вы видите ошибку «Page Not Found» при переходе по домену Netlify. Чаще всего это происходит потому, что Netlify не перенаправляет корневой или произвольный путь на вашу стартовую страницу (index.html). В статье объяснено, как быстро устранить эту проблему и какие сценарии нужно учесть.

Проблема: почему Netlify отдаёт 404 вместо главной

Когда Netlify получает запрос, он ищет файл, соответствующий пути запроса. Для статических сайтов это нормально. Для SPA (React, Vue, Angular) маршрутизация происходит на клиенте, и все запросы к любым путям должны возвращать index.html с кодом 200, чтобы клиентский роутер разобрал путь.

Если правило перенаправления не настроено, сервер вернёт 404 для путей, которые не соответствуют реальным файлам. Именно тогда вы видите ошибку “Page Not Found”.

Когда это происходит чаще всего

• Вы хостите SPA (React Router, Vue Router, Angular) и ожидаете обработку маршрутов на клиенте.
• Файловая структура не содержит index.html в корне публикации или publish directory указан неверно.
• Вы используете статическую генерацию, но не настроили fallback для неизвестных маршрутов.

Быстрое решение: перенаправление всех запросов на index.html

Есть два простых варианта: файл _redirects или netlify.toml. Оба работают на уровне Netlify и решают проблему одинаково.

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

1. Откройте папку публикации (publish directory) — это папка, в которую помещается результат сборки. Для Create React App это обычно папка build или public; для других фреймворков — dist или папка, указанная в настройках Netlify.
2. Создайте файл с именем _redirects (без расширения) в корне publish directory.
3. Добавьте строку перенаправления, которая направляет все пути на index.html, например:

/*    /index.html    200

4. Если вы используете Angular и хотите, чтобы файл _redirects попал в сборку, добавьте его в массив assets в angular.json:

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

Важно: файл _redirects должен оказаться в папке, которую Netlify публикует. Если он лежит в корне репозитория, но не копируется в publish directory, правило не сработает.

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

Если вы предпочитаете конфигурацию в формате TOML, создайте netlify.toml в корне проекта (или в папке публикации) и добавьте блок:

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

netlify.toml удобен, когда вы управляете несколькими правилами, контекстами (production/branch-deploy) и другими настройками сборки.

Проверка и повторный деплой

1. В интерфейсе Netlify откройте страницу сайта и перейдите в Deploy → Deploy settings.
2. Убедитесь, что в Build settings указан правильный publish directory.

3. Закоммитьте и запушьте изменения (_redirects или netlify.toml) в репозиторий.
4. Netlify автоматически запустит новый деплой. Если не сработало, вручную нажмите Trigger Deploy → Deploy Site.
5. Дождитесь окончания сборки.

6. Откройте домен сайта и проверьте разные пути (/, /about, /products/123). Все они должны возвращать содержимое index.html и корректно рендериться клиентским роутером.

Когда это решение не сработает

• Если ваш publish directory настроен неверно и Netlify вовсе не видит index.html.
• Если статические файлы генерируются в другом каталоге, и _redirects не попадает в итоговую сборку.
• Если вы используете серверные функции (Edge Functions, Netlify Functions) с особой логикой маршрутизации — может потребоваться дополнительная конфигурация.
• Если в проекте используется base href (Angular) или publicPath (Webpack) неправильно — маршруты могут ломаться несмотря на перенаправления.

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

• Создать правило в настройках Netlify UI (Redirects) — можно добавлять записи вручную через панель управления сайта.
• Настроить CDN/Reverse proxy перед Netlify (в редких корпоративных случаях) и там реализовать rewrite на index.html.
• Для проектов с SSR или серверными рендерами использовать отдельный хостинг для серверной части и проксировать запросы.

Практическая методология внедрения (шаги)

1. Локальная проверка: соберите проект локально в тот же каталог, который используется для публикации.
2. Поместите _redirects или netlify.toml в папку сборки.
3. Напишите тест-кейсы: открыть корень, открыть несколько вложенных путей, проверить поведение при прямом обновлении страницы.
4. Протестируйте в ветке разработки или на предварительной сборке (branch deploy).
5. Перенесите изменения в основную ветку, дождитесь production-деплоя.
6. Наблюдайте логи сборки и тестируйте конечные маршруты.

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

• При открытии корневого URL сайт загружается без 404.
• При прямом переходе на любой клиентский маршрут (например, /profile или /product/1) страница не возвращает 404 и корректно рендерится.
• В netlify build logs видно, что файл _redirects включён в артефакт публикации (при использовании _redirects).
• Изменения не ломают доступ к реальным статическим файлам (css, js, изображения).

Чек-листы по ролям

Разработчик:

• Убедиться, что index.html генерируется в publish directory.
• Добавить _redirects или netlify.toml.
• Протестировать локально и в branch deploy.

DevOps / инженер релизов:

• Проверить настройки Build settings и publish directory в Netlify.
• Убедиться, что CI собирает артефакты с файлом перенаправлений.

QA:

• Тесты на несколько роутов с ручным обновлением страницы.
• Проверить возврат статических файлов напрямую по URL.

Примеры тестов и приёмки

• Открыть / — ожидание: 200, индексная страница отображается.
• Открыть /non-existent-route — ожидание: 200 и отрисовка SPA (не 404).
• Открыть /static/image.png — ожидание: 200 и корректный контент файла.

Инструменты отладки и советы

• Просмотрите Netlify build log для сообщений о включении _redirects или netlify.toml.
• В браузере откройте Network и посмотрите, какой ответ возвращает сервер (код 200 и index.html или 404).
• Если используете Angular, проверьте base href в index.html и assets в angular.json.
• Если проблема только на кастомном домене — проверьте DNS и настройки домена в Netlify.

Ментальные модели и правила-эвристики

• Правило 200 rewrite для всех путей означает: «сервер отдаёт приложение, клиент решает, какой экран показывать». Это стандарт для SPA.
• Разделяйте реальные статические ресурсы и клиентские маршруты: реальные файлы должны по-прежнему доступаться напрямую.
• Конфигурация должна быть частью сборки, чтобы не зависеть от ручных настроек в UI.

Решение проблем и откат

Если после добавления перенаправления что‑то сломалось:

1. Откатите изменения в репозитории (revert commit).
2. Деплой снова. Это восстановит предыдущее состояние.
3. Проанализируйте логи сборки и повторите внедрение с более узким набором правил.

Короткая памятка для развертывания

• Для SPA: добавьте

/*    /index.html    200

в _redirects или эквивалент в netlify.toml.

• Всегда проверяйте publish directory в настройках Netlify.
• Тестируйте маршруты и статические ресурсы после деплоя.

Заключение

Настройка перенаправлений на Netlify — простая и стандартная операция для корректной работы SPA и современных статических сайтов. Чаще всего достаточно одного правила, которое перенаправляет все запросы на index.html с кодом 200. Если же сайт всё ещё отдает 404, проверьте publish directory, включение файла перенаправлений в сборку и настройки base/publicPath в вашем фреймворке.

Если нужно, могу прислать готовый шаблон _redirects и netlify.toml, адаптированный под ваш стек, или проверить вашу текущую конфигурацию по примерам из репозитория.