Cara Betulkan Halaman Putih Kosong dalam Aplikasi Web Anda

Halaman putih kosong hampir selalu bermaksud salah satu daripada dua perkara: JavaScript aplikasi ranap sebelum melukis apa-apa, atau JavaScript tidak pernah dimuatkan langsung. Buka konsol pelayar (klik kanan → Inspect → Console) dan baca ralat merah pertama, kemudian semak tab Network untuk fail yang gagal dimuatkan. Kebanyakan punca ialah pembolehubah persekitaran yang hilang, laluan asas yang salah, binaan yang tidak selesai, atau ranap dalam satu komponen.

Panduan ini meliputi aplikasi halaman tunggal (SPA) yang dibina dengan React, Vue atau rangka kerja serupa, termasuk aplikasi yang dibuat oleh pembina AI, dan di situlah halaman kosong paling kerap berlaku.

Mengapa halaman itu putih

Aplikasi SPA moden menghantar pelayar fail HTML yang hampir kosong, kira-kira begini:

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

JavaScript kemudian membina keseluruhan halaman di dalam div yang kosong itu. Jika skrip gagal dimuatkan, atau melontarkan ralat sebelum merender, div kekal kosong dan anda melihat putih. Halaman itu tidak “rosak” dengan cara yang kelihatan; ia hanya tidak pernah dilukis.

Sebab itulah pembetulan sentiasa bermula dalam alat pembangun, bukan pada halaman itu sendiri.

Langkah 1: Baca konsol

Buka alat pembangun: klik kanan pada halaman dan pilih Inspect, atau tekan F12 (Cmd+Option+I pada Mac). Pergi ke tab Console dan segarkan halaman.

Lihat ralat merah pertama; ralat seterusnya selalunya kesan sampingan. Apa yang dikatakannya menunjuk kepada punca:

Salin teks ralat penuh, termasuk nama fail dan nombor baris. Jika anda menggunakan pembina AI, tampalkannya terus ke dalam sembang.

Langkah 2: Semak sama ada fail dimuatkan

Buka tab Network, tandakan Disable cache, dan segarkan. Lihat permintaan untuk fail .js dan .css.

• Status 404 pada fail JavaScript: halaman meminta fail yang tidak wujud di pelayan.
• Status 200 tetapi jenisnya text/html: pelayan mengembalikan halaman (selalunya index.html itu sendiri, kerana fallback SPA) dan bukannya skrip. Punca yang sama: fail tidak berada di tempat yang halaman jangka.

Sebab biasa:

Laluan asas yang salah. Jika aplikasi dihidangkan dari sub-folder, seperti example.com/app/, tetapi dibina untuk memuatkan fail dari /assets/..., setiap permintaan skrip tersasar. Dalam Vite ini ialah pilihan base dalam vite.config; dalam Create React App ia medan homepage; dalam Next.js ia basePath. Ia mesti sepadan dengan tempat aplikasi sebenarnya dihidangkan.

index.html yang lapuk. Alat binaan memberi fail nama dengan hash kandungan, seperti index-a1b2c3.js. Selepas deploy baharu, fail lama hilang. Jika pelayar atau CDN masih menyimpan index.html lama dalam cache, ia meminta fail lama dan tidak mendapat apa-apa. Segarkan dengan paksa (Cmd+Shift+R atau Ctrl+Shift+R) untuk mengesahkannya. Penyelesaian jangka panjang ialah menghidangkan index.html dengan header tiada-cache atau cache pendek, manakala fail ber-hash disimpan dalam cache untuk tempoh panjang.

Binaan tidak selesai atau tidak di-deploy. Jika binaan gagal, hos mungkin menghidangkan folder output yang lama atau kosong. Semak log binaan untuk ralat.

Folder yang salah diterbitkan. Hos mesti menghidangkan output binaan (biasanya dist atau build), bukan folder sumber projek. Menghidangkan sumber memberi anda index.html yang menunjuk ke /src/main.tsx, yang tidak dapat dijalankan oleh pelayar.

Langkah 3: Semak pembolehubah persekitaran

Aplikasi bahagian hadapan selalunya membaca tetapan seperti URL API atau kunci awam semasa binaan. Jika pembolehubah hilang pada binaan langsung, kod seperti createClient(undefined, undefined) melontar serta-merta, dan halaman menjadi putih.

Perkara yang perlu diketahui:

• Dalam Vite, hanya pembolehubah dengan awalan VITE_ tersedia dalam kod pelayar, dibaca sebagai import.meta.env.VITE_NAME. Dalam Create React App ia REACT_APP_; dalam Next.js, NEXT_PUBLIC_.
• Nilai ini dimasukkan semasa aplikasi dibina. Menambah pembolehubah selepas binaan tidak berkesan sehingga anda membina dan deploy semula.
• Pelayan tempatan atau mesin anda mungkin ada fail .env yang binaan pengeluaran tidak ada. Tetapkan pembolehubah yang sama pada hos.
• Apa-apa dengan awalan ini berakhir dalam JavaScript awam. Letakkan nilai awam sahaja di sana, jangan sekali-kali kunci rahsia.

Ujian pantas: cari dalam ralat konsol perkataan undefined berhampiran nama tetapan, atau tanya:

Aplikasi yang diterbitkan menunjukkan halaman kosong. Senaraikan setiap pembolehubah persekitaran yang dibaca bahagian hadapan, semak yang mana hilang atau kosong dalam binaan langsung, dan jadikan aplikasi menunjukkan mesej ralat yang jelas dan bukannya halaman kosong apabila satu hilang.

Langkah 4: Betulkan ranap

Jika konsol menunjukkan ralat JavaScript biasa, kod ranap semasa render. Punca biasa dalam aplikasi yang dibina AI:

• Data belum dimuatkan. Komponen membaca user.name sebelum user tiba. Penyelesaiannya ialah keadaan memuat, atau optional chaining (user?.name).
• Data kosong. Akaun baharu tiada rekod, dan kod menganggap senarai mempunyai sekurang-kurangnya satu item.
• Bentuk data yang tidak dijangka. API mengembalikan objek ralat dan bukannya senarai yang kod jangkakan.
• Import yang hilang selepas fail dinamakan semula atau dipindahkan.
• Menggunakan API khusus pelayar semasa server-side rendering, seperti window atau localStorage dalam komponen pelayan Next.js.

Beri AI ralat penuh, halaman, dan siapa yang anda log masuk sebagai:

Halaman Dashboard kosong untuk pengguna baharu. Konsol: TypeError: Cannot read properties of undefined (reading 'map') pada ProjectList.tsx:18. Ia berfungsi untuk akaun saya, yang mempunyai projek. Betulkannya supaya akaun kosong menunjukkan “Tiada projek lagi”, dan semak akaun baharu dalam pratonton.

Langkah 5: Tambah error boundary

Dalam React, satu komponen yang ranap boleh menyahlekapkan keseluruhan aplikasi, itulah sebabnya satu pepijat kecil menghasilkan halaman yang benar-benar kosong. Error boundary ialah komponen yang menangkap ralat render di bawahnya dan memaparkan sandaran.

Tambah error boundary di sekeliling laluan utama yang memaparkan “Ada sesuatu yang tidak kena” dengan butang Muat Semula, dan log ralat ke konsol. Simpan header dan navigasi di luar supaya ia tetap dipaparkan.

Ia tidak membetulkan pepijat, tetapi pelawat melihat mesej dan bukannya skrin kosong, dan anda nampak di mana ia pecah.

Langkah 6: Tiada ralat, masih kosong

Jika konsol bersih dan skrip dimuatkan:

• Semak tab Elements. Adakah terdapat kandungan di dalam <div id="root">? Jika ya, ia dirender tetapi tidak kelihatan: teks putih atas putih, opacity: 0, display: none, atau elemen skrin penuh yang menutupinya.
• Semak penghala. Jika tiada laluan sepadan dengan URL semasa dan tiada laluan “tidak dijumpai”, sesetengah penghala tidak merender apa-apa. Tambah laluan tangkap-semua yang memaparkan halaman 404.
• Semak titik lekap. Kod mesti melekap pada elemen yang wujud. Jika index.html mempunyai id="app" tetapi kod mencari root, tiada apa yang muncul (dan React biasanya mencatat ralat).
• Semak sambungan pelayar. Cuba tetingkap persendirian. Penyekat iklan kadangkala menyekat skrip dengan nama seperti analytics atau ads.

Kosong hanya selepas menyegarkan halaman?

Jika halaman utama berfungsi tetapi menyegarkan /dashboard menunjukkan halaman kosong atau 404, pelayan tidak tahu untuk menghantar index.html bagi laluan aplikasi. Itu masalah fallback penghalaan, yang diliputi dalam cara membetulkan ralat 404 selepas deploy.

Kesilapan biasa

• Membaca ralat terakhir dan bukannya yang pertama. Baris merah pertama biasanya puncanya.
• Menetapkan pembolehubah persekitaran tanpa membina semula. Pembolehubah bahagian hadapan ditetapkan semasa binaan.
• Hanya menguji dengan akaun sendiri. Ranap akaun kosong ialah salah satu punca halaman kosong yang paling biasa.
• Menganggap deploy berjaya. Semak log binaan sebelum menyahpepijat kod.
• Menyalahkan cache pelayar untuk segalanya. Segar semula dengan paksa menyingkirkannya dalam beberapa saat; jika halaman masih kosong, ia sesuatu yang lain.

Halaman kosong dalam Mythex

Jika Pratonton kosong, mula-mula semak aplikasi sedang berjalan (buka Code → terminal), kemudian minta Mythex memulakan pelayan yang betul, klik Refresh pada bar alat pratonton, atau gunakan /fix. Untuk URL yang diterbitkan yang kosong, dokumentasi mencadangkan tunggu seminit dan segarkan dengan paksa, sahkan pembolehubah persekitaran dan pangkalan data ditetapkan sebelum menerbitkan, dan semak had hosting anda. Ingat bahawa aplikasi yang diterbitkan ialah syot kilat: selepas membetulkan sesuatu, terbitkan semula. Jika satu perubahan menyebabkannya, Revert to this point pada balasan terakhir yang baik akan memulihkan projek. Lihat Penyelesaian masalah dan Penyelesaian masalah penerbitan dalam dokumentasi, dan panduan umum kami tentang menyahpepijat aplikasi yang dibina AI.

Senarai semak halaman kosong

• Baca ralat merah pertama dalam Console
• Semak tab Network untuk fail .js/.css yang 404 atau mengembalikan HTML
• Laluan asas sepadan dengan tempat aplikasi dihidangkan
• Binaan selesai, dan folder output binaan ialah yang diterbitkan
• Semua pembolehubah persekitaran bahagian hadapan ditetapkan pada binaan langsung, kemudian dibina semula
• Ranap diperbetulkan, termasuk untuk akaun kosong dan baharu
• Error boundary disediakan supaya ranap akan datang menunjukkan mesej
• Laluan tangkap-semua untuk URL yang tidak dikenali
• Diuji selepas segar semula dengan paksa dan dalam tetingkap persendirian

Soalan lazim