Kaip ištaisyti tuščią baltą puslapį žiniatinklio programėlėje

Tuščias baltas puslapis beveik visada reiškia vieną iš dviejų dalykų: programėlės JavaScript sugedo dar prieš ką nors nupiešdamas, arba JavaScript visai neįsikrovė. Atidarykite naršyklės konsolę (dešiniuoju pelės klavišu → Inspect → Console), perskaitykite pirmą raudoną klaidą, tada patikrinkite Network skirtuką, ar nėra failų, kurie neįsikrovė. Dažniausios priežastys: trūkstamas aplinkos kintamasis, neteisingas bazinis kelias, kūrimas, kuris nebaigtas, arba gedimas viename komponente.

Šis vadovas aprėpia vienos puslapio programėles, sukurtas su React, Vue ar panašiais karkasais (įskaitant DI kūrimo įrankių sukurtas programėles), – čia tuščias puslapis pasitaiko dažniausiai.

Kodėl puslapis baltas

Modernioji vienos puslapio programėlė (SPA) naršyklei siunčia beveik tuščią HTML failą, maždaug tokį:

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

JavaScript tada visą puslapį sukuria tame tuščiame div. Jei skriptas neįsikrauna arba meta klaidą prieš atvaizdavimą, div lieka tuščias ir matote baltą spalvą. Puslapis nėra „sugedęs“ matomu būdu; tiesiog niekada nebuvo nupieštas.

Todėl taisymas visada prasideda kūrėjo įrankiuose, o ne pačiame puslapyje.

1 žingsnis: perskaitykite konsolę

Atidarykite kūrėjo įrankius: dešiniuoju pelės klavišu spustelėkite puslapį ir pasirinkite Inspect, arba paspauskite F12 (Mac – Cmd+Option+I). Eikite į Console skirtuką ir atnaujinkite puslapį.

Pažiūrėkite į pirmą raudoną klaidą; vėlesnės dažnai yra šalutiniai efektai. Tai, ką ji sako, parodo priežastį:

Nukopijuokite visą klaidos tekstą, įskaitant failo pavadinimą ir eilutės numerį. Jei naudojate DI kūrimo įrankį, įklijuokite jį tiesiai į pokalbį.

2 žingsnis: patikrinkite, ar failai įsikrovė

Atidarykite Network skirtuką, pažymėkite Disable cache ir atnaujinkite puslapį. Pažiūrėkite užklausas į .js ir .css failus.

• 404 statusas JavaScript faile: puslapis prašo failo, kurio serveryje nėra.
• 200 statusas, bet tipas text/html: serveris grąžino puslapį (dažnai pačią index.html, dėl SPA atsarginio varianto), o ne skriptą. Ta pati šaknis: failo nėra ten, kur puslapis tikisi.

Dažnos priežastys:

Neteisingas bazinis kelias. Jei programėlė teikiama iš poaplankio, pavyzdžiui example.com/app/, bet buvo sukurta taip, kad failus kraustytų iš /assets/..., kiekviena skripto užklausa nepataiko. Vite tai yra base parinktis vite.config; Create React App – homepage laukas; Next.js – basePath. Jis turi sutapti su vieta, kur programėlė iš tiesų teikiama.

Pasenusi index.html. Kūrimo įrankiai failams suteikia pavadinimus su turinio maiša, pavyzdžiui index-a1b2c3.js. Po naujo diegimo senas failas dingsta. Jei naršyklė ar CDN vis dar turi seną index.html talpykloje, ji prašo seno failo ir nieko negauna. Priverstinis atnaujinimas (Cmd+Shift+R arba Ctrl+Shift+R) tai patvirtina. Ilgalaikis pataisymas – teikti index.html su trumpa arba jokia talpyklos antrašte, o maišytus failus talpinti ilgai.

Kūrimas nebaigtas arba neįdiegtas. Jei kūrimas nepavyko, serveris gali teikti seną arba tuščią rezultato aplanką. Patikrinkite kūrimo žurnalą dėl klaidų.

Publikuojamas neteisingas aplankas. Serveris turi teikti kūrimo rezultatą (dažniausiai dist arba build), o ne projekto šaltinio aplanką. Šaltinio aplankas duoda index.html, nukreipiantį į /src/main.tsx, kurio naršyklės negali paleisti.

3 žingsnis: patikrinkite aplinkos kintamuosius

Priekinės dalies programėlės dažnai nuskaito nustatymus, pavyzdžiui API URL ar viešąjį raktą, kūrimo metu. Jei kintamojo gyvame kūrime nėra, kodas kaip createClient(undefined, undefined) iškart meta klaidą ir puslapis tampa baltas.

Ką žinoti:

• Vite atveju naršyklės kode pasiekiami tik kintamieji su priesaga VITE_, nuskaitomi kaip import.meta.env.VITE_NAME. Create React App – REACT_APP_; Next.js – NEXT_PUBLIC_.
• Šios reikšmės įterpiamos kūrimo metu. Pridėjus kintamąjį po kūrimo, nieko nepasikeičia, kol neperkursite ir neįdiegsite iš naujo.
• Peržiūroje arba jūsų kompiuteryje gali būti .env failas, kurio nėra produkcinio kūrimo metu. Nustatykite tuos pačius kintamuosius serveryje.
• Viskas su šiomis priesagomis patenka į viešą JavaScript. Ten dėkite tik viešąsias reikšmes, niekada slaptųjų raktų.

Greitas patikrinimas: konsolės klaidoje ieškokite undefined šalia nustatymo pavadinimo arba paklauskite:

Publikuota programėlė rodo tuščią puslapį. Išvardink kiekvieną aplinkos kintamąjį, kurį priekinė dalis nuskaito, patikrink, kurie trūksta arba tušti gyvame kūrime, ir padaryk, kad programėlė, jam trūkstant, rodytų aiškų klaidos pranešimą vietoj tuščio puslapio.

4 žingsnis: ištaisykite gedimą

Jei konsolėje matote įprastą JavaScript klaidą, kodas sugedo atvaizdavimo metu. Dažnos priežastys DI sukurtose programėlėse:

• Duomenys dar neįkelti. Komponentas skaito user.name, kol user dar neatkeliavo. Pataisymas – įkėlimo būsena arba pasirenkamasis ženklas (user?.name).
• Tušti duomenys. Naujoje paskyroje nėra įrašų, o kodas tikisi bent vieno elemento sąraše.
• Netikėta duomenų forma. API grąžino klaidos objektą vietoj sąrašo, kurio kodas tikėjosi.
• Trūkstamas importas po to, kai failas buvo pervadintas ar perkeltas.
• Naršyklei skirtos API naudojimas serverio pusės atvaizdavime, pavyzdžiui window ar localStorage Next.js serverio komponente.

Duokite DI visą klaidą, puslapį ir tai, kaip buvote prisijungę:

Skydelio puslapis tuščias naujiems naudotojams. Konsolė: TypeError: Cannot read properties of undefined (reading 'map') faile ProjectList.tsx:18. Mano paskyrai, kuri turi projektų, veikia. Pataisyk taip, kad tuščia paskyra rodytų „Projektų dar nėra“, ir patikrink naują paskyrą peržiūroje.

5 žingsnis: pridėkite klaidų ribą

React programėlėje vienas gendantis komponentas gali nuimti visą programėlę, todėl maža klaida sukelia visiškai tuščią puslapį. Klaidų riba (error boundary) – tai komponentas, kuris sugauna jam pavaldžias atvaizdavimo klaidas ir vietoj to parodo atsarginį variantą.

Įdėk klaidų ribą aplink pagrindinius maršrutus, kuri rodo „Kažkas nepavyko“ su mygtuku Perkrauti, ir įrašo klaidą į konsolę. Antraštę ir navigaciją palik už jos, kad jos vis tiek būtų rodomos.

Ji neištaiso klaidos, bet lankytojai mato pranešimą vietoj tuščio ekrano, o jūs matote, kur tai nutiko.

6 žingsnis: nėra klaidų, bet vis tiek tuščia

Jei konsolė švari ir skriptai įsikrauna:

• Patikrinkite Elements skirtuką. Ar <div id="root"> viduje yra turinio? Jei taip, atvaizdavimas vyksta, bet nematomas: baltas tekstas ant balto, opacity: 0, display: none arba visą ekraną uždengiantis elementas.
• Patikrinkite maršrutizatorių. Jei joks maršrutas neatitinka dabartinio URL ir nėra „nerasta“ maršruto, kai kurie maršrutizatoriai nieko nerodo. Pridėkite visas gaudantį maršrutą, rodantį 404 puslapį.
• Patikrinkite prijungimo tašką. Kodas turi prisijungti prie egzistuojančio elemento. Jei index.html turi id="app", o kodas ieško root, nieko nesimato (ir React paprastai įrašo klaidą).
• Patikrinkite naršyklės plėtinį. Pabandykite privatų langą. Skelbimų blokuotojai kartais blokuoja skriptus su tokiais pavadinimais kaip analytics ar ads.

Tuščia tik atnaujinus puslapį?

Jei pagrindinis puslapis veikia, bet atnaujinus /dashboard rodomas tuščias puslapis ar 404, serveris nežino, kad programėlės maršrutams reikia siųsti index.html. Tai maršrutizavimo atsarginio varianto problema, aprašyta kaip ištaisyti 404 klaidas po diegimo.

Dažniausios klaidos

• Skaitoma paskutinė klaida vietoj pirmosios. Pirmoji raudona eilutė dažniausiai yra priežastis.
• Aplinkos kintamųjų nustatymas be perkūrimo. Priekinės dalies kintamieji fiksuojami kūrimo metu.
• Testavimas tik su savo paskyra. Tuščios paskyros gedimai – viena dažniausių tuščio puslapio priežasčių.
• Prielaida, kad diegimas pavyko. Prieš derindami kodą, patikrinkite kūrimo žurnalą.
• Kaltinimas naršyklės talpykla dėl visko. Priverstinis atnaujinimas tai atmeta per kelias sekundes; jei puslapis vis dar tuščias, priežastis kita.

Tušti puslapiai Mythex

Jei Peržiūra tuščia, pirmiausia patikrinkite, ar programėlė veikia (atidarykite Code → terminal), tada paprašykite Mythex paleisti teisingą serverį, spustelėkite Refresh peržiūros įrankių juostoje arba naudokite /fix. Jei tuščias publikuotas URL, dokumentacija pataria palaukti minutę ir priverstinai atnaujinti, įsitikinti, kad prieš publikavimą nustatyti aplinkos kintamieji ir duomenų bazė, bei patikrinti savo talpinimo limitą. Atminkite, kad publikuota programėlė yra momentinė nuotrauka: ištaisę ką nors, publikuokite iš naujo. Jei pakeitimas tai sukėlė, Revert to this point ties paskutiniu geru atsakymu grąžina projektą atgal. Žr. dokumentacijos trikčių šalinimas ir publikavimo problemų sprendimas, taip pat mūsų bendrą vadovą kaip ištaisyti DI sukurtą programėlę.

Tuščio puslapio kontrolinis sąrašas

• Perskaityta pirmoji raudona klaida Console
• Network skirtuke patikrinti .js/.css failai, kurie rodo 404 arba grąžina HTML
• Bazinis kelias sutampa su vieta, kur programėlė teikiama
• Kūrimas baigtas, ir publikuojamas kūrimo rezultato aplankas
• Visi priekinės dalies aplinkos kintamieji nustatyti gyvame kūrime, tada perkurta
• Gedimas ištaisytas, įskaitant tuščias ir naujas paskyras
• Yra klaidų riba, kad būsimi gedimai rodytų pranešimą
• Nežinomiems URL yra visa gaudantis maršrutas
• Patikrinta po priverstinio atnaujinimo ir privačiame lange

Klausimai