Веб қолданбадағы ақ бос бетті түзету жолы

Ақ бос бет әдетте екі нәрсені білдіреді: қолданбаның JavaScript-і ештеңе салмай тұрып құлады, немесе JavaScript мүлде жүктелмеді. Браузер консолін ашыңыз (тінтуірдің оң жағы → Inspect → Console), бірінші қызыл қатені оқыңыз, содан кейін Network қойындысында жүктелмеген файлдарды тексеріңіз. Ең жиі себептер: жетіспейтін орта айнымалысы, дұрыс емес base path, аяқталмаған құрастыру немесе бір компоненттегі қате.

Бұл нұсқаулық React, Vue немесе ұқсас фреймворктермен жасалған бір беттік қолданбаларға (AI құрастырушылары жасағандарды қоса) арналған, бос беттер ең көп осында кездеседі.

Бет неге ақ

Заманауи бір беттік қолданба (SPA) браузерге шамамен мынадай, іс жүзінде бос HTML файлын жібереді:

<body>
  <div id="root"></div>
  <script type="module" src="/assets/index-a1b2c3.js"></script>
</body>

Содан кейін JavaScript осы бос div ішінде бүкіл бетті құрастырады. Егер скрипт жүктелмесе, немесе рендерден бұрын қате тастаса, div бос қалады және сіз ақ көресіз. Бет көзге көрінетін түрде «бұзылмаған»; ол жай ешқашан салынбаған.

Сондықтан түзету әрқашан беттен емес, даму құралдарынан басталады.

1-қадам: Консольді оқыңыз

Даму құралдарын ашыңыз: бетті тінтуірдің оң жағымен басып Inspect таңдаңыз, немесе F12 басыңыз (Mac-те Cmd+Option+I). Console қойындысына өтіңіз де бетті қайта жүктеңіз.

Бірінші қызыл қатеге қараңыз; кейінгілері көбіне салдары. Ол не айтатыны себепті көрсетеді:

Қатенің толық мәтінін көшіріңіз, файл атымен және жол нөмірімен. AI құрастырушысын пайдалансаңыз, оны бірден чатқа қойыңыз.

2-қадам: Файлдардың жүктелгенін тексеріңіз

Network қойындысын ашыңыз, Disable cache құсбелгісін қойыңыз да бетті қайта жүктеңіз. .js және .css файлдарына сұрауларға қараңыз.

• JavaScript файлында 404 мәртебесі: бет серверде жоқ файлды сұрап жатыр.
• 200 мәртебесі, бірақ түрі text/html: сервер скриптті емес, бетті (көбіне index.html өзін, SPA қайтаруына байланысты) қайтарды. Түбірлік себебі бірдей: файл бет күткен жерде емес.

Жиі кездесетін себептер:

Дұрыс емес base path. Қолданба example.com/app/ ішіндегі папкадан қызмет етсе, бірақ /assets/... файлдарынан жүктеуге құрастырылса, әр скрипт сұрауы өтпейді. Vite-та бұл vite.config ішіндегі base опциясы; Create React App-та homepage өрісі; Next.js-те basePath. Ол қолданба шынымен қызмет ететін жермен сәйкес келуі керек.

Ескірген index.html. Құрастыру құралдары файлдарға хэштелген атау береді, мысалы index-a1b2c3.js. Жаңа орналастырудан кейін ескі файл жоғалады. Егер браузер немесе CDN ескі index.html-ді кэштеп тұрса, ол жоқ файлды сұрайды және ештеңе алмайды. Қатты жаңарту (Cmd+Shift+R немесе Ctrl+Shift+R) мұны растайды. Ұзақ мерзімді түзету — index.html-ді қысқа немесе кэшсіз мерзім тақырыбымен беру, ал хэштелген файлдарды ұзақ кэштеу.

Құрастыру аяқталмаған немесе орналастырылмаған. Құрастыру сәтсіз болса, хост ескі немесе бос шығыс папкасын қызмет етуі мүмкін. Құрастыру журналындағы қателерді тексеріңіз.

Дұрыс емес папка жарияланған. Хост құрастыру нәтижесін (әдетте dist немесе build) қызмет етуі керек, жобаның бастапқы папкасын емес. Бастапқы папканы қызмет етсе, index.html /src/main.tsx-ге сілтеме жасайды, оны браузер іске қоса алмайды.

3-қадам: Орта айнымалыларын тексеріңіз

Фронтенд қолданбалар көбіне API URL немесе ашық кілт сияқты баптауларды құрастыру кезінде оқиды. Тірі құрастыруда айнымалы жетіспесе, createClient(undefined, undefined) сияқты код бірден қате тастайды да бет ақ болады.

Білуге тиісті нәрселер:

• Vite-та тек VITE_ префиксі бар айнымалылар браузер кодында қолжетімді, import.meta.env.VITE_NAME ретінде оқылады. Create React App-та бұл REACT_APP_; Next.js-те NEXT_PUBLIC_.
• Бұл мәндер қолданба құрастырылған кезде енгізіледі. Құрастырудан кейін айнымалы қоссаңыз, қайта құрастырып қайта орналастырмайынша ештеңе өзгермейді.
• Превью немесе жергілікті компьютерде .env файлы болуы мүмкін, ал өндірістік құрастыруда ол жоқ. Бірдей айнымалыларды хостта орнатыңыз.
• Осы префикстері бар кез келген нәрсе жалпыға ортақ JavaScript-ке түседі. Онда тек ашық мәндер болсын, ешқашан құпия кілттер емес.

Жылдам тест: консоль қатесінен баптау атының жанындағы undefined сөзін іздеңіз немесе сұраңыз:

Жарияланған қолданба бос бет көрсетеді. Фронтенд оқитын барлық орта айнымалыларын тізіп шығарыңыз, тірі құрастыруда қайсысы жоқ немесе бос екенін тексеріңіз, және біреуі жоқ болғанда бос бет емес, түсінікті қате хабарламасын көрсетіңіз.

4-қадам: Құлауды түзету

Консольде қалыпты JavaScript қатесі көрінсе, код рендер кезінде құлаған. AI көмегімен жасалған қолданбаларда жиі кездесетін себептер:

• Деректер әлі жүктелмеген. Компонент user келмей тұрып user.name оқиды. Түзету — жүктеу күйі, немесе optional chaining (user?.name).
• Бос деректер. Жаңа аккаунтта жазбалар жоқ, ал код тізімде кем дегенде бір элемент бар деп болжайды.
• Күтпеген деректер пішімі. API күтілген тізімнің орнына қате объектісін қайтарды.
• Жетіспейтін импорт файл атын немесе орнын өзгерткеннен кейін.
• Серверлік рендерде браузерге тән API пайдалану, мысалы Next.js серверлік компонентінде window немесе localStorage.

AI-ға толық қатені, бетті және сіз қай аккаунтпен кірген болсаңыз соны беріңіз:

Dashboard беті жаңа пайдаланушылар үшін бос. Консоль: TypeError: Cannot read properties of undefined (reading 'map'), ProjectList.tsx:18 жолында. Менің аккаунтымда жобалар бар, сондықтан ол жұмыс істейді. Бос аккаунт үшін «Әлі жобалар жоқ» көрсетілетіндей түзетіңіз, және превьюде жаңа аккаунтты тексеріңіз.

5-қадам: Error boundary қосыңыз

React-та бір бұзылған компонент бүкіл қолданбаны алып тастауы мүмкін, сондықтан шағын қате толық бос бет береді. Error boundary — төменгі рендер қателерін ұстап, оның орнына резервтік көрініс көрсететін компонент.

Негізгі маршруттардың айналасына «Бірдеңе дұрыс болмады» деген және Reload батырмасы бар error boundary қосыңыз, ал қатені консольге жазыңыз. Үстіңгі мәзір мен навигация осы boundary-дан тыс қалсын, сонда олар әлі көрінеді.

Бұл қатені түзетпейді, бірақ келушілер бос экранның орнына хабарлама көреді, ал сіз қай жерде бұзылғанын көресіз.

6-қадам: Қате жоқ, бірақ бос

Консоль таза болып, скрипттер жүктелсе:

• Elements қойындысын тексеріңіз. <div id="root"> ішінде мазмұн бар ма? Егер бар болса, ол рендерленген, бірақ көрінбейді: ақ мәтін ақ фонда, opacity: 0, display: none, немесе оны жауып тұрған толық экранды элемент.
• Роутерді тексеріңіз. Ағымдағы URL-ге ешқандай маршрут сәйкес келмесе және «табылмады» маршруты болмаса, кейбір роутерлер ештеңе көрсетпейді. Бет табылмады көрсететін catch-all маршрут қосыңыз.
• Mount нүктесін тексеріңіз. Код бар элементке орнатылуы керек. Егер index.html-де id="app" болса, ал код root іздесе, ештеңе көрінбейді (және React әдетте қате жазады).
• Браузер кеңейтуін тексеріңіз. Жекелеген терезеде қараңыз. Жарнама блоктаушылары кейде analytics немесе ads сияқты атаулы скрипттерді блоктайды.

Бет тек жаңартқанда ғана бос па?

Басты бет жұмыс істейді, бірақ /dashboard-ты жаңартқанда бос бет немесе 404 көрінсе, сервер қолданба маршруттары үшін index.html жіберуді білмейді. Бұл бағыттау қайтаруының мәселесі, оны орналастырғаннан кейінгі 404 қателерін түзету нұсқауында қарастырылған.

Жиі кездесетін қателер

• Соңғы қатені оқу, бірінші емес. Бірінші қызыл жол әдетте себеп.
• Айнымалыларды қайта құрастырмай орнату. Фронтенд айнымалылары құрастыру кезінде бекітіледі.
• Тек өз аккаунтыңызбен тексеру. Бос аккаунттағы құлау — ең жиі бос бет себептерінің бірі.
• Орналастыру сәтті деп болжау. Кодты түзетпес бұрын құрастыру журналын тексеріңіз.
• Бәріне браузер кэшін кінәлау. Қатты жаңарту оны секундта жоққа шығарады; бет әлі бос болса, мәселе басқада.

Mythex-тегі бос беттер

Егер Preview бос болса, алдымен қолданба іске қосылғанын тексеріңіз (Code → terminal ашыңыз), содан кейін Mythex-тен дұрыс серверді іске қосуын сұраңыз, превью құралдар жолағындағы Refresh батырмасын басыңыз, немесе /fix пайдаланыңыз. Жарияланған URL бос болса, құжаттар бір минут күтуді, жариялау алдында орта айнымалылары мен деректер базасы орнатылғанын растауды және хостинг лимитін тексеруді ұсынады. Есте сақтаңыз, жарияланған қолданба — сурет: бірдеңені түзеткеннен кейін қайта жариялаңыз. Егер өзгеріс себеп болса, соңғы жақсы жауаптағы Revert to this point жобаны алдыңғы күйіне қайтарады. Ақаулықтарды түзету және жариялау ақаулықтарын түзету құжаттарын, ал жалпы AI құрастырған қолданбаны түзету нұсқауын қараңыз.

Ақ бет тексеру тізімі

• Консольдегі бірінші қызыл қате оқылды
• Network қойындысында 404 беретін немесе HTML қайтаратын .js/.css файлдары тексерілді
• Base path қолданба қызмет ететін жерге сәйкес
• Құрастыру аяқталды, және жарияланатын папка — құрастыру нәтижесі
• Барлық фронтенд орта айнымалылары тірі құрастыруда орнатылды, содан кейін қайта құрастырылды
• Құлау түзетілді, бос және жаңа аккаунттар үшін де
• Болашақ қателер хабарлама көрсетуі үшін error boundary бар
• Белгісіз URL-дерге catch-all маршрут бар
• Қатты жаңартудан және жекелеген терезеден кейін тексерілді

Сұрақтар