Як виправити помилки 404 після розгортання сайту або застосунку

Якщо ваш застосунок працює локально, але сторінки повертають 404 після розгортання, найчастіша причина — відсутнє маршрутизування односторінкового застосунку (SPA): сервер шукає файл /dashboard, якого немає, бо такий маршрут існує лише в JavaScript. Виправлення — правило-резерв, яке віддає index.html для маршрутів застосунку. Інші причини: відсутні файли у вихідній збірці, шляхи з чутливістю до регістру, різниця в завершальних слешах, неправильний базовий шлях і API-маршрути, які так і не були розгорнуті.

Почніть з того, щоб зафіксувати, яка саме URL дає 404 і як ви на неї потрапили. Закономірність одразу вкаже на причину.

Крок 1: Знайдіть закономірність

Щоб побачити реальний код статусу, відкрийте інструменти розробника (правий клік → Inspect, «Перевірити»), перейдіть на вкладку Network (Мережа), перезавантажте сторінку і подивіться статус першого запиту.

Крок 2: Додайте резервний маршрут SPA

Це класичний випадок. В односторінковому застосунку React, Vue чи Svelte сервер має лише кілька справжніх файлів: index.html і деякі JavaScript та CSS. Маршрути на кшталт /dashboard або /projects/42 обробляє маршрутизатор у браузері.

• Перехід за посиланням працює: маршрутизатор змінює URL і малює нову сторінку, не звертаючись до сервера.
• Оновлення або відкриття посилання напряму не працює: браузер просить у сервера /dashboard, сервер не має такого файлу і повертає 404.

Виправлення — правило, яке каже: якщо запит не збігається з реальним файлом, віддати index.html зі статусом 200 і передати керування маршрутизатору. Спосіб залежить від хоста (перевіряйте актуальну документацію хоста, бо деталі змінюються):

Переконайтеся, що правило не поглинає справжні файли: запити на /assets/app.js мають далі повертати файл JavaScript. Якщо вони повертають index.html, ви отримаєте порожню сторінку з помилкою «Failed to load module script». Див. як виправити порожню білу сторінку.

Також додайте маршрутизатору catch-all маршрут, щоб URL, які не відповідають жодній сторінці, показували зрозуміле повідомлення «Сторінку не знайдено», а не порожнечу.

Якщо ви не можете змінити налаштування сервера, хеш-маршрутизація (URL на кшталт /#/dashboard) уникає проблеми, бо частину після # ніколи не надсилають серверу. Це обхідний шлях, а не перший вибір: URL виглядають гірше й менш зрозумілі для пошукових систем.

Фреймворки, які рендерять сторінки на сервері або генерують їх під час збірки (Next.js, Astro та подібні), зазвичай мають справжні файли або серверні маршрути для кожної сторінки, тож ця проблема там трапляється рідше. Їхній еквівалент — сторінка, яку не згенерували під час збірки.

Крок 3: Перевірте, що справді розгорнуто

Якщо все дає 404, сервер, імовірно, не віддає вашу зібрану програму.

• Правильна папка. Хост має публікувати вихідну збірку (зазвичай dist для Vite, build для Create React App, out для статичного експорту Next.js), а не кореневу папку проєкту.
• Збірка пройшла. Прочитайте лог розгортання. Якщо збірка не вдалася, хост міг не розгорнути нічого або розгорнути стару версію.
• index.html лежить на верхньому рівні опублікованої папки, а не в підпапці.
• Базовий шлях збігається. Якщо застосунок віддається з example.com/app/, його треба зібрати з цим базовим шляхом (параметр base у Vite, basename у React Router), інакше кожен маршрут і ресурс не знайдуться.

Крок 4: Виправте відсутні файли та неправильні шляхи

Коли сторінки завантажуються, але ресурси дають 404:

• Чутливість до регістру. macOS і Windows зазвичай вважають Logo.png і logo.png одним файлом. Більшість серверів Linux — ні. Кожне посилання має точно збігатися з іменем файлу.
• Файли поза збіркою. У Vite файли в public/ копіюються як є і посилаються з кореня (/logo.png). Імпортовані в коді файли збираються разом із застосунком. Файл, що лежить деінде в проєкті, може взагалі не розгорнутися.
• Відносні шляхи. images/photo.jpg резолвиться відносно поточної URL, тож ламається на /blog/post-1. Використовуйте /images/photo.jpg.
• Завантажені файли, збережені на локальний диск. Якщо завантаження користувачів записувалися в папку самого сервера, вони зникають, коли розгортається нова версія. Використовуйте нормальне файлове сховище.

Крок 5: Послідовно обробляйте завершальні слеші

/about і /about/ — різні URL. Хости відрізняються тим, чи додають або прибирають слеш, і невідповідність між вашими посиланнями чи маршрутизатором може дати 404 або цикл редиректів. Оберіть один стиль, зробіть так, щоб ваші посилання його використовували, і налаштуйте хост так, щоб інша форма перенаправлялася на нього. Це також допомагає пошуковим системам, які інакше можуть побачити дві копії кожної сторінки.

Крок 6: Виправте API-маршрути, що дають 404

Якщо сторінка завантажується, але у вкладці Network запити /api/... повертають 404:

• Бекенд не розгорнуто. Статичний хост віддає лише файли; бекенд має працювати десь.
• Шлях маршрутизується інакше в продакшені. У розробці проксі міг переспрямовувати /api на окремий сервер. У продакшені хосту потрібен еквівалентний rewrite або фронтенд має викликати справжню адресу API.
• Резервний маршрут SPA перехопив запит. Запит API, який повертає index.html зі статусом 200, означає, що правило-резерв занадто широке. Виключіть з нього /api/*.

Запити опублікованого застосунку до /api/orders повертають 404, хоча в превью працюють. Перевірте, як /api маршрутизується в превью і в опублікованому застосунку, і зробіть так, щоб опублікований фронтенд звертався до бекенду так само.

Крок 7: Перенаправте старі URL

Якщо ви перейшли з іншого сайту або перебудували структуру, старі URL, якими досі користуються люди і пошукові системи, даватимуть 404. Додайте 301 (постійний) редирект з кожного старого URL на його нове місце. Ведіть список і перевіряйте вибірку після запуску. Наш посібник як перенести сайт WordPress пояснює, як скласти такий список.

Крок 8: Перевірте домен

Якщо застосунок працює за адресою хоста, але дає 404 на вашому власному домені, домен може вказувати на інший проєкт, або хост ще не прив'язав домен до вашого сайту. Перевірте записи DNS і налаштування домену в хості. Див. як підключити власний домен.

Зробіть свою справжню сторінку 404 корисною

Деякі 404 — правильні: людина помилилася в URL. Зробіть цю сторінку корисною:

• Коротке повідомлення і посилання на головну сторінку та ключові розділи
• Пошук, якщо на сайті він є
• Той самий заголовок і навігація, що й на решті сайту

Там, де це дозволяє ваша конфігурація, повертайте справжній статус 404 для неіснуючих сторінок. Повідомлення «не знайдено» зі статусом 200 — це те, що пошукові системи називають м'яким 404: воно марнує їхній час обходу і заплутує індексацію.

Типові помилки

• Тестування лише кліками. Завжди перевіряйте, вставляючи глибокі URL в нову вкладку і оновлюючи сторінку.
• Резерв, який ловить усе. Ресурси й маршрути API повертають index.html, через що з'являються порожні сторінки і заплутані помилки API.
• Невідповідний регістр, який ламається лише на сервері.
• Розгортання вихідної папки замість вихідної збірки.
• Перебудова URL без редиректів. Кожне старе посилання стає 404.

404 у Mythex

У Mythex ви публікуєте з робочого простору, а статичні фронтенди розгортаються як статичні сайти. Якщо опублікована сторінка дає 404, дайте агенту точну URL, скажіть, чи це відбувається при оновленні, чи при переході за посиланням, і що показує вкладка Network, та попросіть перевірити маршрутизацію. Після виправлення опублікуйте знову: живий застосунок — це знімок, доки ви його не опублікуєте повторно. Якщо ви нещодавно змінювали проєкт, а живий сайт виглядає застарілим, опублікуйте знову і зробіть жорстке оновлення сторінки. Використовуйте Fix with AI у діалозі публікації, якщо збірка не вдалася. Див. How to publish і Publish troubleshooting у документації, а також наш посібник як налагоджувати застосунок, створений з ШІ.

Чекліст для 404

• Зафіксовано точні URL, що дають 404, і чи це при оновленні, при переході, чи в обох випадках
• Резервний маршрут SPA віддає index.html для маршрутів застосунку зі статусом 200
• Резерв виключає справжні файли і /api/*
• Маршрутизатор має catch-all маршрут «не знайдено»
• Опублікована папка — це вихідна збірка, і збірка пройшла успішно
• Базовий шлях відповідає місцю, де віддається застосунок
• Регістр імен файлів збігається з усіма посиланнями
• Шляхи до ресурсів починаються з /
• Стиль завершальних слешів послідовний
• API-маршрути розгорнуто і маршрутизовано в продакшені
• Є 301-редиректи для старих URL
• Глибокі посилання перевірено вставкою в нову вкладку

Запитання