Galat validasi skema css-loader adalah salah satu kegagalan build Webpack yang paling umum - ia terpicu sebelum kompilasi dimulai dan memberikan jalur galat yang tampak samar sampai Anda tahu cara membacanya. Panduan ini menjelaskan apa yang memicu galat-galat ini, cara mengurai pesannya, perubahan webpack.config.js mana yang memperbaiki tiap kasus, dan cara memvalidasi konfigurasi agar build berikutnya berhasil pada percobaan pertama.
Apa itu galat validasi skema?
Webpack memvalidasi objek opsi setiap loader terhadap skema JSON sebelum mulai mengompilasi. Skema ini mendefinisikan properti mana yang diizinkan, tipe apa yang diterima, dan nilai mana yang valid. Ketika konfigurasi Anda mengirim properti yang tidak dikenal skema - atau mengirim tipe yang salah untuk properti yang dikenal - Webpack melempar galat validasi skema dan menolak membangun.
Mengapa validasi terjadi sebelum kompilasi
Webpack memvalidasi di muka karena opsi loader memengaruhi cara file diproses. Opsi yang tidak valid bisa menghasilkan keluaran yang salah secara diam-diam jika Webpack mengabaikannya, sehingga validasi ketat saat startup adalah desain yang lebih aman. Konsekuensinya adalah penghentian total sebelum kode tersentuh - tetapi pesan galat selalu memberi tahu persis opsi mana yang salah dan di mana posisinya di pohon konfigurasi Anda.
Format galat
Galat validasi skema css-loader mengikuti struktur yang dapat diprediksi. Ia selalu menyertakan nama loader (css-loader), jalur ke opsi bermasalah di objek konfigurasi Anda (mis. options.localIdentName), masalah spesifik (`properti tidak dikenal, harus salah satu dari nilai yang diizinkan atau harus bertipe [tipe]`), dan sering kali tautan ke dokumentasi loader. Membaca jalur lebih dulu selalu menjadi jalan tercepat menuju perbaikan.
Note
Mengapa css-loader memicunya
css-loader telah mengalami perubahan signifikan pada skema opsinya antar versi mayor. Pengembang yang memperbarui css-loader - atau menyalin webpack.config.js dari tutorial untuk versi lain - sering berakhir dengan opsi yang valid di rilis lama tetapi kini tidak dikenal atau telah direstrukturisasi.
Semua opsi CSS Modules dipindahkan ke bawah opsi modules untuk menghindari pencemaran opsi tingkat atas dan meningkatkan kejelasan skema.
Perubahan merusak v4
Sumber paling umum galat skema css-loader adalah migrasi v3 → v4. Di css-loader v3, opsi CSS Modules berada di tingkat atas objek opsi: localIdentName, camelCase, minimize, dan modules sebagai boolean. Di v4, semua opsi CSS Modules pindah ke sub-objek modules khusus, dan minimize dihapus sepenuhnya (minifikasi CSS kini menjadi bagian css-minimizer-webpack-plugin). Proyek apa pun yang masih memakai sintaks opsi datar v3 dengan instalasi v4+ langsung memicu galat validasi skema.
Pemicu umum lainnya
- Salah ketik pada nama opsi - moduls alih-alih modules, localIdentiyName alih-alih localIdentName
- Tipe nilai salah - mengirim string di mana objek dibutuhkan, atau angka di mana boolean diharapkan
- Opsi yang dihapus - minimize (dihapus di v4), importLoaders sebagai boolean (harus angka), camelCase (dihapus di v6)
- Menyalin config dari tutorial versi lain - jawaban Stack Overflow untuk css-loader v2 masih banyak disajikan mesin pencari
- Dependensi peer yang berkonflik - paket pihak ketiga mengunci versi css-loader lama yang tidak kompatibel dengan konfigurasi Anda
Tip
Membaca pesan galat
Setiap galat validasi skema css-loader memuat informasi yang Anda butuhkan untuk memperbaikinya - jika Anda tahu cara membaca notasi jalurnya. Pesan galat punya tiga bagian penting: nama loader, jalur konfigurasi, dan deskripsi masalah yang spesifik. Fokuslah padanya dengan urutan itu.
Memahami notasi jalur
Notasi jalur mencerminkan struktur webpack.config.js Anda. Jalur seperti module.rules[0].use[1].options.localIdentName berarti: lihat kunci module, lalu rules, lalu item array pertama (indeks 0), lalu use, lalu loader kedua di array use itu (indeks 1), lalu options, lalu properti localIdentName. Ikuti jalur itu di file konfigurasi Anda untuk menemukan baris persis yang menyebabkan galat.
Tiga subtipe galat
| Subtipe galat | Pesan memuat | Artinya | Perbaikan |
|---|---|---|---|
| Properti tidak dikenal | "has an unknown property" | Properti tidak ada di versi ini | Hapus atau ganti nama properti |
| Tipe salah | "should be a [type]" | Properti benar, tipe nilai salah | Ubah nilai ke tipe yang benar |
| Nilai tidak valid | "should be one of the allowed" | Properti benar, nilai di luar himpunan yang diizinkan | Gunakan salah satu nilai valid yang tercantum |
| Properti tambahan | "additionalProperties is false" | Objek memiliki kunci di luar skema | Hapus kunci yang tidak tercantum dari objek |
Subtipe «harus salah satu dari yang diizinkan» selalu mencantumkan opsi valid sebaris dalam galat. Subtipe «properti tidak dikenal» tidak menyarankan alternatif - Anda perlu memeriksa dokumentasi css-loader terkini untuk nama baru atau padanan properti. Gunakan Validator Konfigurasi Webpack untuk mendapatkan semua galat sekaligus alih-alih menemukannya satu per satu lewat build berulang.
Warning
Cara memperbaiki galat css-loader
Perbaikannya selalu perubahan tertarget pada objek opsi css-loader di webpack.config.js Anda. Jalani langkah-langkah ini secara berurutan agar galat terselesaikan dengan rapi tanpa memunculkan galat baru.
Baca pesan galat lengkap dan salin jalurnya
Gulir melewati stack trace ke bagian ValidationError dan salin pesan lengkapnya. Ia menyebut nama loader (css-loader), jalur konfigurasi persis, dan masalahnya. Jalur itu memberi tahu entri rules mana dan posisi mana di array use yang memuat objek opsi tidak valid.
Temukan rule di webpack.config.js
Temukan entri module.rules yang memuat file .css. Biasanya tampak seperti test untuk file .css dengan style-loader dan css-loader beserta objek opsi. Objek opsi di dalam entri css-loader adalah tempat semua galat skema berasal. Buka objek itu dan bandingkan dengan daftar opsi valid untuk versi css-loader yang terpasang.
Terapkan perbaikan yang tepat untuk subtipe galat Anda
Untuk galat properti tidak dikenal: ganti nama atau pindahkan properti ke lokasi barunya. localIdentName menjadi modules.localIdentName. minimize dihapus - pasang css-minimizer-webpack-plugin secara terpisah. camelCase dihapus - gunakan opsi exportLocalsConvention di objek modules sebagai gantinya. Untuk galat tipe salah: ubah modules: true menjadi objek dengan mode: 'local' jika Anda butuh konfigurasi CSS Modules, atau biarkan sebagai boolean jika tidak.
Validasi config yang diperbaiki sebelum membangun ulang
Tempelkan webpack.config.js yang diperbarui ke Validator Konfigurasi Webpack untuk memastikan semua galat skema teratasi sebelum menjalankan build penuh. Ini menangkap galat sekunder akibat perbaikan dan menghemat satu siklus build lagi.
Validator Konfigurasi Webpack
Tempelkan webpack.config.js Anda dan validasi seketika semua opsi loader - mendeteksi galat skema css-loader, rule modul tidak valid, dan kesalahan konfigurasi keluaran sebelum build berikutnya.
Kesalahan konfigurasi css-loader yang umum
Inilah galat opsi spesifik yang paling sering muncul dalam kegagalan validasi skema css-loader. Setiap entri menunjukkan pola config yang rusak, pengganti yang benar, dan versi css-loader mana yang terdampak perubahan itu.
localIdentName di tingkat atas (v3 → v4)
Di css-loader v3, localIdentName adalah opsi tingkat atas yang mengendalikan pembuatan nama kelas CSS Modules. Di v4+, ia pindah ke dalam objek modules. Perbaikannya adalah menyarangkannya di dalam modules dengan properti localIdentName yang diisi pola Anda. Pesan galatnya berbunyi options has an unknown property 'localIdentName' - ini adalah galat migrasi css-loader nomor satu.
Opsi minimize dihapus (v4+)
Opsi minimize dihapus dari css-loader di v4. Minifikasi CSS kini ditangani terpisah oleh css-minimizer-webpack-plugin di array optimization.minimizer. Hapus minimize sepenuhnya dari opsi css-loader Anda dan tambahkan css-minimizer-webpack-plugin ke build Anda jika minifikasi diperlukan. Validator CSS dapat membantu memastikan keluaran CSS benar setelah berganti alat minifikasi.
Opsi camelCase dihapus (v6)
css-loader v6 menghapus opsi camelCase tingkat atas. Penggantinya adalah modules.exportLocalsConvention, yang menerima camelCase, camelCaseOnly, dashes, atau dashesOnly. Perbarui opsi Anda untuk mengatur exportLocalsConvention di dalam objek modules. Tanpa perubahan ini, instalasi v6 apa pun dengan properti camelCase lama memicu galat properti tidak dikenal.
| Opsi lama (rusak) | Versi css-loader | Pengganti yang benar |
|---|---|---|
| options.localIdentName | v4+ | options.modules.localIdentName |
| options.minimize | v4+ | plugin css-minimizer-webpack-plugin |
| options.camelCase | v6+ | options.modules.exportLocalsConvention |
| options.modules: true | v4+ (untuk kustomisasi) | options.modules: { mode: "local", ... } |
| options.importLoaders: true | semua | options.importLoaders: 1 (angka, bukan boolean) |
| options.sourceMap: "inline" | v4+ | options.sourceMap: true (hanya boolean) |
Note
Memvalidasi konfigurasi webpack Anda
Cara paling efisien menyelesaikan galat skema css-loader - terutama setelah peningkatan versi mayor - adalah memvalidasi seluruh webpack.config.js sekaligus alih-alih menemukan galat satu build demi satu build. Beberapa alat membuat ini cepat.
Validator Konfigurasi Webpack
Validator Konfigurasi Webpack menerima webpack.config.js lengkap Anda dan melaporkan semua pelanggaran skema di setiap loader, plugin, dan opsi tingkat atas dalam satu lintasan. Ia menampilkan notasi jalur yang sama seperti yang Webpack pakai di galat runtime, sehingga Anda bisa mencocokkan keluarannya dengan galat yang Anda lihat di terminal. Tempelkan config, dapatkan semua masalah sekaligus, perbaiki, lalu tempel lagi untuk konfirmasi - tanpa siklus build.
Periksa dulu berkas config untuk galat sintaks JavaScript
Jika Webpack gagal bahkan mem-parsing webpack.config.js Anda karena galat sintaks JavaScript - kurung kurawal tak berpasangan, koma yang hilang, atau spread tidak valid - Anda akan melihat galat parsing Node.js alih-alih galat validasi skema. Gunakan Validator Sintaks JavaScript untuk menyingkirkan masalah sintaks sebelum men-debug validasi skema.
Memvalidasi berkas konfigurasi terkait
css-loader jarang menjadi satu-satunya berkas konfigurasi dalam pipeline build. Jika Anda memakai PostCSS untuk transformasi, Validator Konfigurasi PostCSS menangkap galat urutan plugin dan dependensi yang hilang di postcss.config.js. Jika Anda memakai stylelint untuk pemeriksaan kualitas CSS, Validator Konfigurasi Stylelint memvalidasi .stylelintrc Anda sebelum mengganggu build. Validator Konfigurasi ESLint berguna jika rantai build Anda juga menjalankan ESLint - salah konfigurasi di sana bisa muncul sebagai galat build yang menyerupai galat loader.
Validator Konfigurasi PostCSS
Validasi postcss.config.js untuk galat urutan plugin dan opsi - menangkap masalah konfigurasi yang sering menyertai galat skema css-loader pada setup Webpack yang kompleks.
css-loader dengan PostCSS dan CSS Modules
Sebagian besar setup Webpack produksi memakai css-loader bersama PostCSS dan CSS Modules. Masing-masing menambah opsi sendiri dan potensi galat skema sendiri. Memahami interaksinya mencegah konflik konfigurasi yang paling umum.
Opsi importLoaders
Ketika PostCSS berjalan pada file CSS sebelum css-loader, Anda harus menyetel importLoaders: 1 (atau lebih) di opsi css-loader agar pernyataan @import dalam CSS juga diproses PostCSS. Tanpa itu, file yang diimpor melewati PostCSS. Kesalahan umum adalah menyetel importLoaders: true - ini memicu galat validasi skema karena opsi harus berupa angka, bukan boolean. Setel nilainya ke jumlah loader yang berjalan sebelum css-loader dalam rantai.
CSS Modules dengan nama kelas kustom
Kustomisasi nama kelas CSS Modules pindah ke sub-objek modules di css-loader v4. Konfigurasi CSS Modules lengkap dengan pola identitas kustom memakai mode, localIdentName, dan exportLocalsConvention - masing-masing sebagai opsi terpisah dengan batasan skema sendiri. Mengirim salah satunya di tingkat atas options alih-alih di dalam modules menghasilkan galat properti tidak dikenal.
Opsi url dan import
Opsi url dan import milik css-loader mengendalikan apakah loader menyelesaikan referensi url() dan pernyataan @import. Keduanya menerima boolean atau objek dengan fungsi filter. Mengirim fungsi polos - alih-alih objek dengan properti filter - memicu galat skema karena skema opsi mengharapkan objek dengan properti filter, bukan fungsi telanjang. Selalu bungkus fungsi filter dalam bentuk objek yang diharapkan.
Warning
Key takeaways
- Galat validasi skema css-loader terpicu sebelum kompilasi dan selalu menyebut jalur persis opsi yang tidak valid - baca jalurnya lebih dulu, bukan stack trace.
- Penyebab paling umum adalah memakai sintaks opsi css-loader v3 (localIdentName datar, minimize, camelCase) pada instalasi v4+ atau v6+.
- Di css-loader v4+, semua opsi CSS Modules pindah ke dalam sub-objek modules - localIdentName menjadi modules.localIdentName.
- minimize dihapus di v4 - gunakan css-minimizer-webpack-plugin di optimization.minimizer sebagai gantinya.
- importLoaders harus berupa angka (mis. 1), bukan boolean - mengirim true memicu galat validasi tipe.
- Gunakan Validator Konfigurasi Webpack untuk menangkap semua galat skema dalam satu lintasan sebelum membangun ulang.
- Periksa juga config terkait - salah konfigurasi PostCSS, ESLint, dan Stylelint sering menyertai galat css-loader di pipeline yang kompleks.