Как да поправите грешките 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 към отделен сървър. В продукция хостингът се нуждае от еквивалентно пренаписване или фронтендът трябва да вика реалния адрес на API-то.
• Резервният път е уловил заявката. API заявка, която връща index.html със статус 200, означава, че правилото за резервен път е твърде широко. Изключете /api/* от него.

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

Стъпка 7: Пренасочете старите URL адреси

Ако сте се преместили от друг сайт или сте пренаредили структурата, старите URL адреси, които хората и търсачките още ползват, ще дават 404. Добавете 301 (постоянно) пренасочване от всеки стар URL към новото му място. Пазете списък и тествайте извадка след старта. Нашето ръководство за миграция на WordPress сайт обяснява как да изградите този списък.

Стъпка 8: Проверете домейна

Ако приложението работи на адреса на хостинга, но дава 404 на персоналния ви домейн, домейнът може да сочи към грешния проект или хостингът още да няма прикачен домейна към сайта ви. Проверете DNS записите и настройките на домейна в хостинга. Вижте как да свържете персонален домейн.

Направете реалната си страница 404 полезна

Някои 404 са правилни: някой е сбъркал URL адреса. Направете тази страница полезна:

• Кратко съобщение и връзка към началната страница и ключовите раздели
• Търсачка, ако сайтът има търсене
• Същият header и навигация като останалата част от сайта

Където настройката ви позволява, връщайте истински статус 404 за страниците, които не съществуват. Съобщение „не е намерено“ с статус 200 е това, което търсачките наричат мек 404, и може да губи време за обхождане и да обърка индексирането.

Чести грешки

• Тестване само с кликане. Винаги тествайте, като поставите дълбоки URL адреси в нов таб и презаредите.
• Резервен път, който улавя всичко. Ресурсите и API маршрутите връщат index.html, което води до празни страници и объркващи API грешки.
• Несъвпадение на главни и малки букви, което се чупи само на сървъра.
• Разгръщане на изходната папка вместо изхода от билда.
• Пренареждане на URL адреси без пренасочвания. Всеки стар линк става 404.

404 в Mythex

В Mythex публикувате от работното пространство, а статичните фронтенди се разгръщат като статични сайтове. Ако публикувана страница дава 404, дайте на агента точния URL, дали се случва при презареждане или при клик, и какво показва раздела Network, и го помолете да провери маршрутизацията. Публикувайте отново след поправката, защото живото приложение е снимка, докато не го публикувате наново. Ако наскоро сте променили проекта и живият сайт изглежда стар, публикувайте отново и презаредете с принудително обновяване. Използвайте Fix with AI в прозореца за публикуване, ако билдът се провали. Вижте Как да публикувате и Отстраняване на проблеми при публикуване в документацията, както и нашето ръководство за отстраняване на грешки в приложение, създадено с AI.

Контролен списък за 404

• Отбелязано е точно кои URL адреси дават 404 и дали при кликане, при презареждане или при двете
• Резервният път за SPA сервира index.html за маршрутите на приложението, със статус 200
• Резервният път изключва истинските файлове и /api/*
• Рутерът има catch-all маршрут за „не е намерено“
• Публикувана е папката с изхода от билда и билдът е успешен
• Базовият път съвпада с мястото, където се сервира приложението
• Писането на имената на файловете с главни и малки букви съвпада с всяка препратка
• Пътищата към ресурсите започват с /
• Стилът на наклонената черта в края е последователен
• API маршрутите са разгърнати и маршрутизирани в продукция
• Има 301 пренасочвания за старите URL адреси
• Дълбоките връзки са тествани, като са поставени в нов таб

Въпроси