როგორ გავასწოროთ ცარიელი თეთრი გვერდი ვებ აპში
ცარიელი თეთრი გვერდი თითქმის ყოველთვის ორი რამეს ნიშნავს: აპის 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 fallback-ის გამო), სკრიპტის ნაცვლად. იგივე ძირითადი მიზეზი: ფაილი იქ არ არის, სადაც გვერდი ელოდება.
ჩვეულებრივი მიზეზები:
არასწორი base path. თუ აპი ქვესაქაღალდიდან მუშაობს, მაგალითად example.com/app/, მაგრამ აგებული იყო ფაილების /assets/...-დან ჩატვირთვაზე, ყველა სკრიპტის მოთხოვნა მიუწვდომელი იქნება. Vite-ში ეს არის vite.config-ის base ოფცია; Create React App-ში — homepage ველი; Next.js-ში — basePath. ის უნდა ემთხვეოდეს იმ ადგილს, სადაც აპი რეალურად მუშაობს.
მოძველებული index.html. build ინსტრუმენტები ფაილებს ჰეშირებულ სახელს აძლევენ, მაგალითად index-a1b2c3.js. ახალი დეპლოის შემდეგ ძველი ფაილი აღარ არსებობს. თუ ბრაუზერს ან CDN-ს ჯერ კიდევ აქვს ქეშში ძველი index.html, ის ძველ ფაილს ითხოვს და არაფერს იღებს. hard refresh (Cmd+Shift+R ან Ctrl+Shift+R) ამას ადასტურებს. გრძელვადიანი გამოსავალი არის index.html-ის მოკლე ან არაქეშირებადი სათაურებით მიწოდება, ხოლო ჰეშირებული ფაილები დიდ ხანს ქეშირდება.
build არ დასრულდა ან არ დეპლოიდა. თუ 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: გაასწორეთ crash
თუ კონსოლი ჩვეულებრივ JavaScript შეცდომას აჩვენებს, კოდი რენდერისას ავარიულდა. AI-ით აშენებულ აპებში გავრცელებული მიზეზებია:
- მონაცემები ჯერ არ ჩამოტვირთულა. კომპონენტი კითხულობს
user.name-ს მაშინ, როცაuserჯერ არ მოსულა. გამოსავალი არის ჩატვირთვის მდგომარეობა, ან optional chaining (user?.name). - ცარიელი მონაცემები. ახალ ანგარიშს ჩანაწერები არ აქვს, და კოდი ივარაუდებს, რომ სიაში მინიმუმ ერთი ელემენტია.
- მოულოდნელი მონაცემის ფორმა. API შეცდომის ობიექტი დააბრუნა სიის ნაცვლად, რომელსაც კოდი ელოდა.
- იმპორტი აკლია ფაილის სახელის შეცვლის ან გადატანის შემდეგ.
- ბრაუზერისთვის განკუთვნილი API სერვერზე რენდერისას, მაგალითად
windowანlocalStorageNext.js სერვერულ კომპონენტში.
მიეცით AI-ს სრული შეცდომა, გვერდი და ის, თუ როგორ იყავით შესული:
Dashboard გვერდი ცარიელია ახალი მომხმარებლებისთვის. კონსოლი:
TypeError: Cannot read properties of undefined (reading 'map')ProjectList.tsx:18-ზე. ჩემს ანგარიშზე მუშაობს, რადგან მას პროექტები აქვს. გაასწორე, რომ ცარიელი ანგარიში აჩვენებდეს „ჯერ პროექტები არ არის", და შეამოწმე ახალი ანგარიში გადახედვაში.
ნაბიჯი 5: დაამატეთ error boundary
React-ში ერთმა ავარიულმა კომპონენტმა შეიძლება მთელი აპი მოხსნას, და ამიტომ პატარა შეცდომა სრულიად ცარიელ გვერდს იძლევა. error boundary არის კომპონენტი, რომელიც მის ქვეშ არსებულ რენდერის შეცდომებს იჭერს და მაგივრად ჩვენების შეტყობინებას აჩვენებს.
დაამატე error boundary მთავარ მარშრუტებს, რომელიც აჩვენებს „რაღაც არასწორად წავიდა" შეტყობინებას Reload ღილაკით და ჩაწერს შეცდომას კონსოლში. სათაური და ნავიგაცია დატოვე გარეთ, რომ მაინც დაიხატოს.
ის შეცდომას არ ასწორებს, მაგრამ ვიზიტორები ცარიელი ეკრანის მაგივრად შეტყობინებას ხედავენ, და თქვენ ხედავთ, სად გატყდა.
ნაბიჯი 6: შეცდომები არ არის, მაგრამ მაინც ცარიელია
თუ კონსოლი სუფთაა და სკრიპტები იტვირთება:
- შეამოწმეთ Elements ჩანართი. არის თუ არა შინაარსი
<div id="root">-ში? თუ კი, ის რენდერდება, მაგრამ უჩინარია: თეთრი ტექსტი თეთრზე,opacity: 0,display: none, ან მთელი ეკრანის ელემენტი, რომელიც მას ფარავს. - შეამოწმეთ მარშრუტიზატორი. თუ მიმდინარე URL-ს არცერთი მარშრუტი არ ემთხვევა და არ არის „ვერ მოიძებნა" მარშრუტი, ზოგი მარშრუტიზატორი არაფერს არ რენდერებს. დაამატეთ დამჭერი მარშრუტი, რომელიც 404 გვერდს აჩვენებს.
- შეამოწმეთ mount წერტილი. კოდი უნდა მიუერთდეს ელემენტს, რომელიც არსებობს. თუ
index.html-ში არისid="app", კოდი კიroot-ს ეძებს, არაფერი გამოჩნდება (და React ჩვეულებრივ შეცდომას ჩაწერს). - შეამოწმეთ ბრაუზერის გაფართოება. სცადეთ პირადი ფანჯარა. რეკლამის დამბლოკავები ზოგჯერ აბლოკავს სკრიპტებს სახელებით
analyticsანads.
ცარიელია მხოლოდ გვერდის განახლების შემდეგ?
თუ მთავარი გვერდი მუშაობს, მაგრამ /dashboard-ის განახლება ცარიელ გვერდს ან 404-ს იძლევა, სერვერმა არ იცის, რომ აპის მარშრუტებისთვის index.html უნდა გააგზავნოს. ეს არის fallback-ის მარშრუტიზაციის პრობლემა, რომელიც განხილულია სახელმძღვანელოში როგორ გავასწოროთ 404 შეცდომები დეპლოის შემდეგ.
გავრცელებული შეცდომები
- კონსოლში ბოლო შეცდომის კითხვა პირველის ნაცვლად. პირველი წითელი ხაზი ხშირად არის მიზეზი.
- გარემოს ცვლადების დაყენება build-ის გარეშე. ფრონტენდის ცვლადები build-ის დროს ფიქსირდება.
- მხოლოდ საკუთარი ანგარიშით ტესტირება. ცარიელი ანგარიშის შეცდომები ცარიელი გვერდის ერთ-ერთი ყველაზე ხშირი მიზეზია.
- დეპლოი წარმატებული ჰგონია. build-ის ჟურნალი შეამოწმეთ კოდის გამართვამდე.
- ბრაუზერის ქეშის დადანაშაულება ყველაფერში. hard refresh ამას წამებში გამორიცხავს; თუ გვერდი მაინც ცარიელია, მიზეზი სხვაა.
ცარიელი გვერდები Mythex-ში
თუ გადახედვა ცარიელია, ჯერ შეამოწმეთ, მუშაობს თუ არა აპი (გახსენით Code → terminal), შემდეგ სთხოვეთ Mythex-ს სწორი სერვერის გაშვება, დააწკაპუნეთ Refresh-ზე გადახედვის ზოლში, ან გამოიყენეთ /fix. თუ გამოქვეყნებული URL ცარიელია, დოკუმენტაცია გირჩევთ ერთი წუთის მოცდას და hard refresh-ს, გარემოს ცვლადებისა და მონაცემთა ბაზის დაყენების შემოწმებას გამოქვეყნებამდე, და თქვენი ჰოსტინგის ლიმიტის შემოწმებას. გახსოვდეთ, რომ გამოქვეყნებული აპი სნეპშოტია: რაიმეს გასწორების შემდეგ კვლავ გამოაქვეყნეთ. თუ ცვლილებამ გამოიწვია, Revert to this point ბოლო კარგ პასუხზე პროექტს უკან აბრუნებს. იხილეთ Troubleshooting და Publish troubleshooting დოკუმენტაციაში, და ჩვენი ზოგადი სახელმძღვანელო AI-ით აშენებული აპის გამართვა.
ცარიელი გვერდის საკონტროლო სია
- წაკითხულია პირველი წითელი შეცდომა Console-ში
- Network ჩანართში შემოწმებულია
.js/.cssფაილები, რომლებიც 404-ს იძლევა ან HTML-ს აბრუნებს - base path ემთხვევა იმ ადგილს, სადაც აპი მუშაობს
- build დასრულდა და build-ის შედეგის საქაღალდე არის ის, რაც გამოქვეყნდება
- ყველა ფრონტენდის გარემოს ცვლადი დაყენებულია ცოცხალ build-ზე, შემდეგ ხელახლა აშენდა
- crash გასწორებულია, მათ შორის ცარიელი და ახალი ანგარიშებისთვის
- error boundary დამატებულია, რომ მომავალი crash-ები შეტყობინებას აჩვენებდეს
- უცნობი URL-ებისთვის დამჭერი მარშრუტი არსებობს
- შემოწმებულია hard refresh-ის შემდეგ და პირად ფანჯარაში
კითხვები
რატომ აჩვენებს ჩემი 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 არის კომპონენტი, რომელიც მის ქვეშ არსებული ნაწილის რენდერის შეცდომებს იჭერს და მთელი გვერდის მოხსნის ნაცვლად ჩვენების შეტყობინებას აჩვენებს.