Näin korjaat valkoisen tyhjän sivun verkkosovelluksessasi

Valkoinen tyhjä sivu tarkoittaa lähes aina jompaakumpaa: sovelluksen JavaScript kaatui ennen kuin mitään piirrettiin, tai JavaScript ei latautunut lainkaan. Avaa selaimen konsoli (oikea klikkaus → Tarkista → Console), lue ensimmäinen punainen virhe ja tarkista sen jälkeen Network-välilehdeltä tiedostot, jotka eivät latautuneet. Yleisimpiä syitä ovat puuttuva ympäristömuuttuja, väärä base-polku, keskeneräinen build tai kaatuminen yhdessä komponentissa.

Tämä opas koskee yhden sivun sovelluksia, jotka on rakennettu Reactilla, Vuella tai vastaavalla kehyksellä (myös tekoälyrakentajien tekemiä sovelluksia), ja joissa tyhjät sivut ovat yleisimpiä.

Miksi sivu on valkoinen

Nykyaikainen yhden sivun sovellus (SPA) lähettää selaimelle lähes tyhjän HTML-tiedoston, suunnilleen tällaisen:

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

JavaScript rakentaa sitten koko sivun tuohon tyhjään div-elementtiin. Jos skripti ei lataudu tai heittää virheen ennen renderöintiä, div pysyy tyhjänä ja näet valkoista. Sivu ei ole näkyvästi ”rikki”; se vain ei koskaan piirtynyt.

Siksi korjaus alkaa aina kehittäjätyökaluista, ei itse sivulta.

Vaihe 1: Lue konsoli

Avaa kehittäjätyökalut: oikea klikkaus sivulla ja Tarkista, tai F12 (Mac: Cmd+Option+I). Siirry Console-välilehdelle ja päivitä sivu.

Katso ensimmäistä punaista virhettä; myöhemmät ovat usein sivuvaikutuksia. Mitä se sanoo, osoittaa syyn:

Kopioi koko virheteksti, mukaan lukien tiedostonimi ja rivinumero. Jos käytät tekoälyrakentajaa, liitä se suoraan chatiin.

Vaihe 2: Tarkista, että tiedostot latautuivat

Avaa Network-välilehti, ruksaa Disable cache ja päivitä sivu. Katso .js- ja .css-tiedostojen pyyntöjä.

• Tila 404 JavaScript-tiedostossa: sivu pyytää tiedostoa, jota ei ole palvelimella.
• Tila 200, mutta tyyppi on text/html: palvelin palautti sivun (usein index.html itse, SPA-varasäännön vuoksi) skriptin sijaan. Sama perimmäinen syy: tiedosto ei ole siellä, missä sivu sen odottaa.

Yleisiä syitä:

Väärä base-polku. Jos sovellus on palvelussa alikansiossa, kuten esimerkki.fi/app/, mutta se on rakennettu lataamaan tiedostot polusta /assets/..., kaikki skriptipyynnöt jäävät väliin. Vitessä tämä on base-asetus vite.config-tiedostossa; Create React Appissa se on homepage-kenttä; Next.js:ssä basePath. Sen pitää vastata sitä, mistä sovellus oikeasti palvellaan.

Vanhentunut index.html. Build-työkalut antavat tiedostoille sisältöhashin sisältävät nimet, kuten index-a1b2c3.js. Uuden julkaisun jälkeen vanha tiedosto on poissa. Jos selain tai CDN on yhä välimuistissa vanhan index.html-tiedoston, se pyytää vanhaa tiedostoa eikä saa mitään. Kova päivitys (Cmd+Shift+R tai Ctrl+Shift+R) vahvistaa tämän. Pitkän aikavälin korjaus on palvella index.html lyhyellä tai ilman välimuistia, kun hashatut tiedostot ovat pitkään välimuistissa.

Build ei valmistunut tai sitä ei julkaistu. Jos build epäonnistui, host voi palvella vanhaa tai tyhjää tulostuskansiota. Tarkista build-loki virheiden varalta.

Väärä kansio on julkaistu. Hostin pitää palvella build-tulos (yleensä dist tai build), ei projektin lähdekansiota. Lähteen palveleminen antaa index.html-tiedoston, joka osoittaa kohtaan /src/main.tsx, jota selaimet eivät osaa ajaa.

Vaihe 3: Tarkista ympäristömuuttujat

Frontend-sovellukset lukevat usein asetuksia, kuten API-osoitteen tai julkisen avaimen, buildin aikana. Jos muuttuja puuttuu live-buildista, koodi kuten createClient(undefined, undefined) heittää virheen heti ja sivu muuttuu valkoiseksi.

Asioita, jotka kannattaa tietää:

• Vitessä vain VITE_-alkuiset muuttujat ovat saatavilla selainkoodissa, ja ne luetaan muodossa import.meta.env.VITE_NIMI. Create React Appissa etuliite on REACT_APP_; Next.js:ssä NEXT_PUBLIC_.
• Nämä arvot upotetaan buildin aikana. Muuttujan lisääminen buildin jälkeen ei tee mitään, ennen kuin rakennat ja julkaiset uudelleen.
• Paikallisella koneella tai esikatselussa voi olla .env-tiedosto, jota tuotantobuildilla ei ole. Aseta samat muuttujat hostille.
• Kaikki näillä etuliitteillä varustetut päätyy julkiseen JavaScriptiin. Laita sinne vain julkisia arvoja, ei koskaan salaisia avaimia.

Nopea testi: etsi konsolivirheestä undefined asetuksen nimen läheltä, tai kysy:

Julkaistu sovellus näyttää tyhjän sivun. Listaa jokainen ympäristömuuttuja, jonka frontend lukee, tarkista mitkä puuttuvat tai ovat tyhjiä live-buildissa, ja tee sovelluksesta niin, että se näyttää selkeän virheviestin tyhjän sivun sijaan, kun muuttuja puuttuu.

Vaihe 4: Korjaa kaatuminen

Jos konsolissa on tavallinen JavaScript-virhe, koodi kaatui renderöinnin aikana. Tyypillisiä syitä tekoälyllä rakennetuissa sovelluksissa:

• Dataa ei ole vielä ladattu. Komponentti lukee user.name-kentän ennen kuin user on saapunut. Korjaus on lataustila tai valinnainen ketjutus (user?.name).
• Tyhjä data. Uudella tilillä ei ole tietueita, ja koodi olettaa, että lista sisältää vähintään yhden kohteen.
• Odottamaton datan muoto. API palautti virheobjektin siitä listasta, jonka koodi odotti.
• Puuttuva import sen jälkeen, kun tiedosto on nimetty uudelleen tai siirretty.
• Selaimelle tarkoitetun API:n käyttö palvelinpuolen renderöinnissä, kuten window tai localStorage Next.js-palvelinkomponentissa.

Anna tekoälylle koko virhe, sivu ja se, millä tilillä olit kirjautuneena:

Dashboard-sivu on tyhjä uusille käyttäjille. Konsoli: TypeError: Cannot read properties of undefined (reading 'map') tiedostossa ProjectList.tsx:18. Se toimii tililläni, jossa on projekteja. Korjaa niin, että tyhjä tili näyttää ”Ei vielä projekteja”, ja tarkista uusi tili esikatselussa.

Vaihe 5: Lisää virherajoitin

Reactissa yksi kaatuva komponentti voi purkaa koko sovelluksen, minkä vuoksi pieni virhe tuottaa täysin tyhjän sivun. Virherajoitin on komponentti, joka kiinnittää alapuolellaan olevat renderöintivirheet ja näyttää varan niiden sijaan.

Lisää virherajoitin pääreittien ympärille, joka näyttää ”Jotain meni pieleen” -viestin ja Lataa uudelleen -painikkeen ja kirjaa virheen konsoliin. Pidä yläpalkki ja navigaatio rajoittimen ulkopuolella, jotta ne näkyvät yhä.

Se ei korjaa virhettä, mutta kävijät näkevät viestin tyhjän näytön sijaan, ja sinä näet, missä se hajosi.

Vaihe 6: Ei virheitä, mutta yhä tyhjä

Jos konsoli on puhdas ja skriptit latautuvat:

• Tarkista Elements-välilehti. Onko <div id="root">-elementin sisällä sisältöä? Jos on, sovellus renderöityy mutta on näkymätön: valkoinen teksti valkoisella, opacity: 0, display: none tai koko näytön kokoinen elementti peittää sen.
• Tarkista reititin. Jos mikään reitti ei vastaa nykyistä URL-osoitetta eikä ”ei löytynyt” -reittiä ole, jotkut reitittimet eivät renderöi mitään. Lisää catch-all-reitti, joka näyttää 404-sivun.
• Tarkista liitoskohta. Koodin pitää liittyä elementtiin, joka on olemassa. Jos index.html sisältää id="app" ja koodi etsii root-elementtiä, mitään ei näy (ja React yleensä kirjaa virheen).
• Tarkista selainlaajennus. Kokeile yksityistä ikkunaa. Mainoksenestäjät estävät joskus skriptejä, joiden nimi sisältää sanoja kuten analytics tai ads.

Tyhjä vain sivun päivityksen jälkeen?

Jos etusivu toimii, mutta /dashboard-sivun päivitys näyttää tyhjän sivun tai 404:n, palvelin ei tiedä lähettää index.html-tiedostoa sovelluksen reiteille. Se on varasäännön reititysongelma, jota käsitellään kohdassa 404-virheiden korjaaminen julkaisun jälkeen.

Yleisimmät virheet

• Luetaan viimeistä virhettä ensimmäisen sijaan. Ensimmäinen punainen rivi on yleensä syy.
• Ympäristömuuttujien asettaminen ilman uudelleenbuildiä. Frontend-muuttujat kiinnitetään buildin aikana.
• Testataan vain omalla tilillä. Tyhjän tilin kaatumiset ovat yksi yleisimmistä tyhjän sivun syistä.
• Oletetaan, että julkaisu onnistui. Tarkista build-loki ennen koodin vianetsintää.
• Selaimen välimuistin syyttäminen kaikesta. Kova päivitys sulkee sen pois sekunneissa; jos sivu on yhä tyhjä, syy on jossakin muualla.

Tyhjät sivut Mythexissä

Jos Esikatselu on tyhjä, tarkista ensin, että sovellus on käynnissä (avaa Code → terminal), ja pyydä sitten Mythexia käynnistämään oikea palvelin, klikkaa Päivitä esikatselun työkalupalkissa tai käytä /fix-komentoa. Jos julkaistu URL on tyhjä, dokumentaation mukaan kannattaa odottaa minuutti ja tehdä kova päivitys, varmistaa, että ympäristömuuttujat ja tietokanta asetettiin ennen julkaisua, ja tarkistaa hostauksen kiintiö. Muista, että julkaistu sovellus on kuvaaja: kun korjaat jotain, julkaise uudelleen. Jos muutos aiheutti ongelman, Palauta tähän kohtaan viimeisellä toimivalla vastauksella palauttaa projektin. Katso Vianmääritys ja julkaisun vianmääritys dokumentaatiosta sekä yleinen oppaamme tekoälyllä rakennetun sovelluksen virheenkorjauksesta.

Tyhjän sivun tarkistuslista

• Luettu konsolin ensimmäinen punainen virhe
• Tarkistettu Network-välilehdeltä .js- ja .css-tiedostot, jotka antavat 404:n tai palauttavat HTML:ää
• Base-polku täsmää siihen, mistä sovellus palvellaan
• Build valmistui ja julkaistava kansio on build-tuloksen kansio
• Kaikki frontend-ympäristömuuttujat asetettu live-buildille, ja build tehty uudelleen
• Kaatuminen korjattu, mukaan lukien tyhjät ja uudet tilit
• Virherajoitin paikallaan, jotta tulevat kaatumiset näyttävät viestin
• Catch-all-reitti tuntemattomille URL-osoitteille
• Testattu kovan päivityksen jälkeen ja yksityisessä ikkunassa

Kysymykset