Ինչպես շտկել սպիտակ դատարկ էջը ձեր վեբ հավելվածում

Սպիտակ դատարկ էջը գրեթե միշտ նշանակում է երկու բաներից մեկը․ հավելվածի JavaScript-ը կոտրվել է, նախքան որևէ բան նկարելը, կամ JavaScript-ը ընդհանրապես չի բեռնվել։ Բացեք բրաուզերի կոնսոլը (աջ կտտոց → Inspect → Console), կարդացեք առաջին կարմիր սխալը և ապա ստուգեք Network ներդիրը՝ ձախողված ֆայլերի համար։ Ամենատարածված պատճառներն են բացակայող միջավայրի փոփոխականը, սխալ base path-ը, չավարտված build-ը կամ կոմպոնենտի կոտրվածքը։

Այս ուղեցույցը վերաբերում է մեկ էջի (SPA) հավելվածներին, որոնք կառուցված են 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 ներդիր և թարմացրեք էջը։

Նայեք առաջին կարմիր սխալին․ հետագա սխալները հաճախ կողմնակի հետևանքներ են։ Այն, ինչ ասում է, ցույց է տալիս պատճառը․

Կոնսոլի հաղորդագրություն (տիպային ձևակերպում)	Ինչ է նշանակում	Գնացեք
`Cannot read properties of undefined (reading '...')`	Կոդը սպասում էր տվյալների, որոնք չկային	Քայլ 4
`... is not defined` / `... is not a function`	Բացակայող ներմուծում, փոփոխական կամ կարգավորում	Քայլ 4 կամ Քայլ 3
`Failed to load module script: Expected a JavaScript module script but the server responded with a MIME type of "text/html"`	Սկրիպտի URL-ը վերադարձրել է HTML էջ՝ JavaScript-ի փոխարեն	Քայլ 2
`Uncaught SyntaxError: Unexpected token '<'`	Նույն բանը․ HTML է եղել այնտեղ, որտեղ սպասվում էր JavaScript	Քայլ 2
`supabaseUrl is required`, `Missing API key` կամ նման	Միջավայրի փոփոխականը դատարկ է	Քայլ 3
`Access to fetch ... has been blocked by CORS policy`	Մեկ այլ դոմենի հարցումը արգելափակվել է	Տես ինչպես շտկել CORS սխալները
Ոչ մի սխալ	Մատուցումը աշխատել է, բայց ոչինչ չի ցույց տալիս, կամ CSS-ը թաքցնում է այն	Քայլ 6

Պատճենեք սխալի ամբողջ տեքստը, ներառյալ ֆայլի անունը և տողի համարը։ Եթե օգտագործում եք AI կառուցող, տեղադրեք այն անմիջապես զրույցում։

Քայլ 2. Ստուգեք, թե արդյոք ֆայլերը բեռնվել են

Բացեք Network ներդիրը, նշեք Disable cache-ը և թարմացրեք։ Նայեք .js և .css ֆայլերի հարցումներին։

Կարգավիճակ 404 JavaScript ֆայլի վրա․ էջը խնդրում է ֆայլ, որը սերվերի վրա չկա։
Կարգավիճակ 200, բայց տեսակը text/html․ սերվերը վերադարձրել է էջ (հաճախ հենց index.html-ը, SPA հետադարձի պատճառով) սկրիպտի փոխարեն։ Նույն արմատական պատճառը․ ֆայլը չի գտնվում այնտեղ, որտեղ էջը սպասում է։

Սովորական պատճառները․

Սխալ base path։ Եթե հավելվածը սպասարկվում է ենթաթղթապանակից, օրինակ՝ example.com/app/, բայց build-ված է այնպես, որ ֆայլերը բեռնի /assets/...-ից, յուրաքանչյուր սկրիպտի հարցում բաց է թողնում։ Vite-ում դա vite.config-ի base տարբերակն է․ Create React App-ում՝ homepage դաշտը․ Next.js-ում՝ basePath-ը։ Այն պետք է համընկնի այն վայրի հետ, որտեղ հավելվածը իրականում սպասարկվում է։

Հնացած index.html։ Build գործիքները ֆայլերին տալիս են բովանդակության հեշ, օրինակ՝ index-a1b2c3.js։ Նոր տեղակայումից հետո հին ֆայլը վերանում է։ Եթե բրաուզերը կամ CDN-ը դեռ քեշում է հին index.html-ը, այն խնդրում է հին ֆայլը և ոչինչ չի ստանում։ Կոշտ թարմացումը (Cmd+Shift+R կամ Ctrl+Shift+R) հաստատում է սա։ Երկարաժամկետ շտկումը index.html-ը սպասարկելն է կարճ կամ առանց քեշի վերնագրով, մինչդեռ հեշավորված ֆայլերը երկար ժամանակ են քեշավորվում։

Build-ը չի ավարտվել կամ չի տեղակայվել։ Եթե build-ը ձախողվել է, հոսթը կարող է սպասարկել հին կամ դատարկ արդյունքի թղթապանակ։ Ստուգեք build-ի մատյանը սխալների համար։

Տեղակայված է սխալ թղթապանակը։ Հոսթը պետք է սպասարկի build-ի արդյունքը (սովորաբար dist կամ build), ոչ թե նախագծի սկզբնական թղթապանակը։ Սկզբնական կոդի սպասարկումը տալիս է index.html, որը ցույց է տալիս /src/main.tsx-ին, որը բրաուզերները չեն կարող գործարկել։

Քայլ 3. Ստուգեք միջավայրի փոփոխականները

Ճակատային հավելվածները հաճախ կարդում են կարգավորումներ, ինչպիսիք են API URL-ը կամ հանրային բանալին, build ժամանակ։ Եթե փոփոխականը բացակայում է կենդանի build-ում, կոդը, ինչպիսին է createClient(undefined, undefined), անմիջապես կոտրվում է, և էջը դառնում է սպիտակ։

Իմանալ պետք է հետևյալը․

Vite-ում միայն VITE_ նախածանցով փոփոխականներն են հասանելի բրաուզերի կոդում, կարդացվում են որպես import.meta.env.VITE_NAME։ Create React App-ում դա REACT_APP_-ն է․ Next.js-ում՝ NEXT_PUBLIC_-ը։
Այս արժեքները ներդրվում են build ժամանակ։ Փոփոխական ավելացնելը build-ից հետո ոչինչ չի անում, մինչև չկառուցեք և չտեղակայեք կրկին։
Նախադիտումը կամ տեղական մեքենան կարող է ունենալ .env ֆայլ, որը արտադրական build-ը չունի։ Նույն փոփոխականները սահմանեք հոստի վրա։
Այս նախածանցներով ամեն ինչ հայտնվում է հանրային JavaScript-ում։ Դրանց մեջ դրեք միայն հանրային արժեքներ, երբեք գաղտնի բանալիներ։

Արագ փորձարկում․ որոնեք կոնսոլի սխալում undefined բառը կարգավորման անվան մոտ, կամ խնդրեք․

Արտադրական հավելվածը ցույց է տալիս դատարկ էջ։ Թվարկիր յուրաքանչյուր միջավայրի փոփոխական, որը կարդում է ճակատը, ստուգիր, թե որոնք են բացակայում կամ դատարկ կենդանի build-ում, և ստիպիր հավելվածը ցույց տալ հստակ սխալի հաղորդագրություն, երբ որևէ բացակայում է, այլ ոչ թե դատարկ էջ։

Քայլ 4. Շտկեք կոտրվածքը

Եթե կոնսոլը ցույց է տալիս սովորական JavaScript սխալ, կոդը կոտրվել է մատուցման ժամանակ։ AI-ով կառուցված հավելվածներում տարածված պատճառներն են․

Տվյալները դեռ չեն բեռնվել։ Կոմպոնենտը կարդում է user.name-ը, նախքան user-ը ստացվի։ Շտկումը բեռնման վիճակն է կամ optional chaining-ը (user?.name)։
Դատարկ տվյալներ։ Նոր հաշիվն ունի ոչ մի գրառում, և կոդը ենթադրում է, որ ցուցակում առնվազն մեկ տարր կա։
Անսպասելի տվյալների ձև։ API-ն վերադարձրել է սխալի օբյեկտ այն ցուցակի փոխարեն, որը կոդը սպասում էր։
Բացակայող ներմուծում, երբ ֆայլը վերանվանվել կամ տեղափոխվել է։
Բրաուզերին միայն API-ի օգտագործումը սերվերային մատուցման ժամանակ, օրինակ՝ window կամ localStorage Next.js սերվերային կոմպոնենտում։

Տվեք AI-ին ամբողջ սխալը, էջը և այն, թե որ հաշվով էիք մուտք գործած․

Dashboard էջը դատարկ է նոր օգտատերերի համար։ Կոնսոլ՝ TypeError: Cannot read properties of undefined (reading 'map') ProjectList.tsx:18-ում։ Աշխատում է իմ հաշվի համար, որն ունի նախագծեր։ Շտկիր այնպես, որ դատարկ հաշիվը ցույց տա «Դեռ նախագծեր չկան», և ստուգիր նոր հաշիվը նախադիտման մեջ։

Քայլ 5. Ավելացրեք error boundary

React-ում մեկ կոտրվող կոմպոնենտը կարող է ամբողջ հավելվածը ապամոնտաժել, ինչի պատճառով փոքր սխալը ստեղծում է լրիվ սպիտակ էջ։ Error boundary-ն այն կոմպոնենտն է, որը բռնում է մատուցման սխալները իր տակ և փոխարենը ցույց է տալիս պահուստային տարբերակ։

Ավելացրու error boundary հիմնական երթուղիների շուրջ, որը ցույց է տալիս «Something went wrong» Reload կոճակով, և սխալը գրանցում է կոնսոլում։ Պահիր վերնագիրը և նավիգացիան դրսում, որպեսզի դրանք դեռ ցուցադրվեն։

Դա սխալը չի շտկում, բայց այցելուները տեսնում են հաղորդագրություն սպիտակի փոխարեն, և դուք տեսնում եք, թե որտեղ է կոտրվել։

Քայլ 6. Սխալներ չկան, բայց դեռ դատարկ է

Եթե կոնսոլը մաքուր է, և սկրիպտները բեռնվում են․

Ստուգեք Elements ներդիրը։ Կա՞ բովանդակություն <div id="root">-ի ներսում։ Եթե այո, այն մատուցվում է, բայց անտեսանելի է․ սպիտակ տեքստ սպիտակ ֆոնի վրա, opacity: 0, display: none, կամ ամբողջ էկրանը ծածկող տարր։
Ստուգեք երթուղիչը։ Եթե ընթացիկ URL-ին ոչ մի երթուղի չի համապատասխանում, և չկա «չի գտնվել» երթուղի, որոշ երթուղիչներ ոչինչ չեն մատուցում։ Ավելացրեք catch-all երթուղի, որը ցույց է տալիս 404 էջ։
Ստուգեք միացման կետը։ Կոդը պետք է միանա գոյություն ունեցող տարրի մեջ։ Եթե index.html-ում id="app" կա, բայց կոդը փնտրում է root, ոչինչ չի երևում (և React-ը սովորաբար սխալ է գրանցում)։
Ստուգեք բրաուզերի ընդլայնումը։ Փորձեք գաղտնի պատուհան։ Գովազդի արգելափակիչները երբեմն արգելափակում են սկրիպտներ այնպիսի անուններով, ինչպիսիք են analytics կամ ads։

Դատարկ է միայն էջը թարմացնելուց հետո՞

Եթե գլխավոր էջը աշխատում է, բայց /dashboard-ը թարմացնելը ցույց է տալիս դատարկ էջ կամ 404, սերվերը չգիտի, որ պետք է ուղարկի index.html հավելվածի երթուղիների համար։ Դա հետադարձման երթուղավորման խնդիր է, որը նկարագրված է ինչպես շտկել 404 սխալները տեղակայումից հետո ուղեցույցում։

Սովորական սխալներ

Կարդալ վերջին սխալը առաջինի փոխարեն։ Առաջին կարմիր տողը սովորաբար պատճառն է։
Միջավայրի փոփոխականներ սահմանել առանց նորից build անելու։ Ճակատային փոփոխականները ֆիքսվում են build ժամանակ։
Փորձարկել միայն սեփական հաշվով։ Դատարկ հաշվի կոտրվածքները դատարկ էջերի ամենատարածված պատճառներից են։
Ենթադրել, որ տեղակայումը աշխատել է։ Ստուգեք build-ի մատյանը, նախքան կոդը վրիպազերծելը։
Ամեն ինչում մեղադրել բրաուզերի քեշը։ Կոշտ թարմացումը դա վայրկյաններում է բացառում․ եթե էջը դեռ դատարկ է, խնդիրը այլ բան է։

Դատարկ էջեր Mythex-ում

Եթե Preview-ն դատարկ է, նախ ստուգեք, որ հավելվածը աշխատում է (բացեք Code → terminal), ապա խնդրեք Mythex-ին գործարկել ճիշտ սերվերը, սեղմեք Refresh նախադիտման գործիքագոտում, կամ օգտագործեք /fix։ Հրապարակված URL-ի համար, որը դատարկ է, փաստաթղթերը խորհուրդ են տալիս մեկ րոպե սպասել և կոշտ թարմացնել, հաստատել, որ միջավայրի փոփոխականները և տվյալների բազան կարգավորված են հրապարակումից առաջ, և ստուգել ձեր հոսթինգի սահմանաչափը։ Հիշեք, որ հրապարակված հավելվածը ստատիկ պատկեր է․ ինչ-որ բան շտկելուց հետո կրկին հրապարակեք։ Եթե փոփոխությունը խնդիր է առաջացրել, Revert to this point վերջին լավ պատասխանի վրա վերադարձնում է նախագիծը։ Տես Troubleshooting և Publish troubleshooting փաստաթղթերում, և մեր ընդհանուր ուղեցույցը՝ AI-ով կառուցված հավելվածի վրիպազերծման մասին։

Սպիտակ էջի ստուգաթերթ

Կարդացել եք կոնսոլի առաջին կարմիր սխալը
Ստուգել եք Network ներդիրը .js/.css ֆայլերի համար, որոնք 404 են կամ վերադարձնում են HTML
Base path-ը համընկնում է այն վայրի հետ, որտեղ սպասարկվում է հավելվածը
Build-ը ավարտվել է, և տեղակայվող թղթապանակը build-ի արդյունքն է
Բոլոր ճակատային միջավայրի փոփոխականները սահմանված են կենդանի build-ի համար, ապա կառուցվել է կրկին
Կոտրվածքը շտկված է, ներառյալ դատարկ և նոր հաշիվների համար
Error boundary կա, որպեսզի ապագա կոտրվածքները ցույց տան հաղորդագրություն
Catch-all երթուղի անհայտ URL-երի համար
Փորձարկվել է կոշտ թարմացումից հետո և գաղտնի պատուհանում

Հարցեր

Ինչու՞ իմ React հավելվածը ցույց է տալիս սպիտակ դատարկ էջ։

Սովորաբար այն պատճառով, որ JavaScript-ը կոտրվել է՝ նախքան որևէ բան մատուցելը, կամ որ JavaScript ֆայլը երբեք չի բեռնվել։ Բացեք բրաուզերի կոնսոլը․ այնտեղ կարմիր սխալը ձեզ կասի, թե որ է, և ֆայլը ու տողը, որտեղ տեղի ունեցավ։

Ինչու՞ հավելվածը տեղում աշխատում է, բայց տեղակայումից հետո դատարկ է։

Ամենատարածված պատճառներն են միջավայրի փոփոխականները, որոնք երբեք չեն սահմանվել կենդանի build-ի համար, JavaScript և CSS ֆայլերը, որոնք պահանջվում են սխալ ուղուց (base path անհամապատասխանություն), և հին քեշավորված index.html, որը ցույց է տալիս դեպի այնպիսի ֆայլեր, որոնք այլևս գոյություն չունեն։

Ի՞նչ է նշանակում «Failed to load module script»։

Բրաուզերը խնդրել է JavaScript ֆայլ, բայց ստացել է HTML էջ՝ սովորաբար կայքի index.html-ը կամ սխալի էջ։ Ֆայլի ուղին սխալ է կամ ֆայլը գոյություն չունի սերվերի վրա, ուստի ստուգեք build-ի արդյունքը և հավելվածի base path կարգավորումը։

Ինչպե՞ս կանխեմ, որ մի սխալը ամբողջ էջը դատարկ չթողնի։

Ավելացրեք error boundary։ React-ում error boundary-ն այն կոմպոնենտն է, որը բռնում է մատուցման սխալները իր տակ գտնվող էջի մասում և ցույց է տալիս պահուստային հաղորդագրություն՝ ամբողջը հեռացնելու փոխարեն։