Mekanisme Source Maps digunakan untuk memetakan kode sumber program ke skrip yang dihasilkan atas dasar mereka. Terlepas dari kenyataan bahwa topik tersebut bukanlah hal baru dan sejumlah artikel telah ditulis di atasnya (misalnya, ini , ini, dan ini ), beberapa aspek masih perlu klarifikasi. Artikel ini adalah upaya untuk merampingkan dan mensistematisasikan semua yang diketahui tentang topik ini dalam bentuk yang singkat dan dapat diakses.
Artikel Source Maps dipertimbangkan dalam kaitannya dengan pengembangan klien di lingkungan browser populer (misalnya, DevTools Google Chrome), meskipun cakupannya tidak terikat dengan bahasa atau lingkungan tertentu. Sumber utama untuk Source Maps adalah, tentu saja, standar , meskipun belum diadopsi (status - proposal), tetapi masih banyak didukung oleh browser.
Pekerjaan pada Source Maps dimulai pada akhir 2000-an, dengan versi pertama yang dibuat untuk plugin Firebug Closure Inspector. Versi kedua dirilis pada 2010 dan berisi perubahan dalam hal mengurangi ukuran file peta. Versi ketiga dikembangkan sebagai bagian dari kolaborasi antara Google dan Mozilla dan diusulkan pada 2011 (terakhir direvisi pada 2013).
Saat ini, di lingkungan pengembangan klien, ada situasi di mana kode sumber hampir tidak pernah secara langsung diintegrasikan ke dalam halaman web, tetapi melewati berbagai tahap pemrosesan sebelum itu: minifikasi, optimisasi, penggabungan, apalagi, kode sumber itu sendiri dapat ditulis dalam bahasa yang memerlukan transpilasi ... Dalam hal ini, untuk keperluan debugging, diperlukan suatu mekanisme yang memungkinkan Anda untuk mengamati kode asli yang dapat dibaca manusia dalam debugger.
Source Maps membutuhkan file-file berikut:
- sebenarnya menghasilkan file javascript
- set file sumber yang digunakan untuk membuatnya
- file peta memetakan mereka satu sama lain
File peta
Seluruh pekerjaan Source Maps didasarkan pada file peta, yang mungkin terlihat seperti ini:
{
"version":3,
"file":"index.js",
"sourceRoot":"",
"sources":["../src/index.ts"],
"names":[],
"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,SAAS,SAAS;IACd,MAAM,OAAO,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;",
"sourcesContent": []
}
Biasanya, nama file peta adalah jumlah dari nama skrip yang dimilikinya, dengan penambahan ekstensi ".map", bundle.js - bundle.js.map. Ini adalah file json biasa dengan bidang-bidang berikut:
- "Versi" - Versi Peta Sumber;
- “File” - (opsional) nama file yang dihasilkan, yang menjadi milik file peta saat ini;
- "SourceRoot" - awalan (opsional) untuk jalur ke sumber file;
- "Sumber" - daftar jalur ke sumber file (diselesaikan dengan cara yang sama seperti alamat src dari tag skrip, Anda dapat menggunakan file: //.);
- "Nama" - daftar nama variabel dan fungsi yang telah mengalami perubahan dalam file yang dihasilkan;
- "Pemetaan" - koordinat variabel pemetaan dan fungsi file sumber ke file yang dihasilkan dalam format Base64 VLQ;
- "SourcesContent" - (opsional) dalam hal file peta mandiri, daftar baris, yang masing-masing berisi teks sumber file dari sumber;
Unduh Peta Sumber
Agar browser memuat file peta, salah satu metode berikut dapat digunakan:
- File JavaScript dilengkapi dengan tajuk HTTP: SourceMap: <url> (X-SourceMap yang sudah usang: <url> sebelumnya digunakan)
- file JavaScript yang dihasilkan memiliki komentar khusus seperti:
//# sourceMappingURL=<url> ( CSS /*# sourceMappingURL=<url> */)
Dengan demikian, setelah memuat file peta, browser akan menarik sumber dari bidang "sumber" dan, menggunakan data di bidang "pemetaan", akan menampilkannya pada skrip yang dihasilkan. Di tab Sumber DevTools, Anda dapat menemukan kedua opsi.
File pseudo-protocol: // dapat digunakan untuk menunjukkan path. Juga, <url> dapat menyertakan seluruh konten file peta dalam encoding Base64. Dalam terminologi Webpack, Sumber Maps seperti ini disebut peta sumber inline.
//# sourceMappingURL=data:application/json;charset=utf-8;base64,<source maps Base64 code>
Sumber Maps memuat kesalahan
, map- -, Network DevTools. , map-, Console DevTools : «DevTools failed to load SourceMap: ...». , : «Could not load content for ...».
File peta mandiri
Kode file sumber dapat dimasukkan secara langsung dalam file peta di bidang "sourcesContent", jika bidang ini ada, tidak perlu mengunduhnya secara terpisah. Dalam hal ini, nama file di "sumber" tidak mencerminkan alamat asli mereka dan dapat sepenuhnya arbitrer. Itulah sebabnya, di tab Sumber di DevTools, Anda dapat melihat "protokol" aneh: webpack: //, ng: //, dll.
Pemetaan
Inti dari mekanisme pemetaan adalah bahwa koordinat (baris / kolom) dari nama-nama variabel dan fungsi dalam file yang dihasilkan dipetakan ke koordinat dalam file kode sumber yang sesuai. Agar mekanisme tampilan berfungsi, informasi berikut diperlukan:
(# 1) nomor baris dalam file yang dihasilkan;
(# 2) nomor kolom dalam file yang dihasilkan;
(# 3) indeks sumber di "sumber";
(# 4) nomor baris sumber;
(# 5) nomor kolom sumber;
Semua data ini berada di bidang "pemetaan", nilainya berupa string panjang dengan struktur dan nilai khusus yang disandikan dalam Base64 VLQ.
Baris dibagi dengan titik koma (;) menjadi beberapa bagian yang sesuai dengan garis-garis dalam file yang dihasilkan (# 1).
Setiap bagian dipisahkan oleh koma (,) ke dalam segmen, yang masing-masing dapat berisi nilai 1,4 atau 5:
- nomor kolom dalam file yang dihasilkan (# 2);
- indeks sumber di "sumber" (# 3);
- nomor baris sumber (# 4);
- nomor kolom sumber (# 5);
- indeks variabel / nama fungsi dari daftar nama;
Nilai-nilai nomor baris dan kolom adalah relatif, menunjukkan offset relatif terhadap koordinat sebelumnya dan hanya yang pertama dari awal file atau bagian.
Setiap nilai adalah nomor Base64 VLQ. VLQ (Variabel-panjang kuantitas) adalah prinsip pengkodean angka yang sewenang-wenang besar menggunakan jumlah biner blok biner dengan panjang tetap.
Source Maps menggunakan blok enam-bit, yang dipesan dari rendah ke tinggi. Bit ke-6 tertinggi dari setiap blok (bit lanjutan) dicadangkan, jika diatur, maka blok saat ini diikuti oleh blok berikutnya dari nomor yang sama, jika diatur ulang, urutannya selesai.
Karena Source Maps harus memiliki tanda, bit tanda juga dicadangkan untuknya, tetapi hanya di blok pertama dari urutan tersebut. Seperti yang diharapkan, bit tanda yang disetel berarti angka negatif.
Jadi, jika angka dapat dikodekan dalam satu blok tunggal, itu tidak bisa menjadi modulo 15 (1111 2 ), karena dua bit dicadangkan di blok enam bit pertama dari urutan: bit kelanjutan akan selalu dihapus, bit tanda akan diatur tergantung pada tanda nomor.
Blok VLQ enam-bit dipetakan ke pengkodean Base64, di mana setiap urutan enam-bit dipetakan ke karakter ASCII tertentu.
Kami memecahkan kode angka mE. Balikkan urutannya, bagian terakhir adalah Em. Kami memecahkan kode angka dari Base64: E - 000100, m - 100110. Pada yang pertama, kami membuang bit kelanjutan tertinggi dan dua nol terkemuka - 100. Pada yang kedua, kami membuang kelanjutan tertinggi dan bit tanda rendah (bit tanda dibersihkan - angka positif) - 0011. Sebagai hasilnya, kami mendapatkan 100 0011 2 , yang sesuai dengan desimal 67.
Dimungkinkan dalam arah yang berlawanan, mengkodekan 41. Kode binernya adalah 101001 2, kami membagi menjadi dua blok: bagian tinggi - 10, bagian rendah (selalu 4-bit) - 1001. Ke bagian tinggi kami menambahkan bit kelanjutan orde tinggi (dibersihkan) dan tiga nol terkemuka - 000010. Ke bagian rendah kami menambahkan bit kelanjutan orde tinggi (set) dan bit tanda paling tidak signifikan (dibersihkan - angka positif) - 110010. Kami menyandikan angka di Base64: 000010 - C, 110010 - y. Kami membalikkan pesanan dan, sebagai hasilnya, kami memperoleh yC. Perpustakaan
dengan nama yang sama sangat berguna untuk bekerja dengan VLQ .