JavaScript Source Map 詳解
上周， jQuery 1.9發布。
這是 2.0 版之前的最后一個新版本，有很多新功能，其中一個就是支持 Source Map。
訪問 http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js，打開壓縮后的版本，滾動到底部，你可以看到最后一行是這樣的：
//@ sourceMappingURL=jquery.min.map
這就是 Source Map。它是一個獨立的 map 文件，與源碼在同一個目錄下，你可以點擊進去，看看它的樣子。
這是一個很有用的功能，本文將詳細講解這個功能。
一、從源碼轉換講起
JavaScript 腳本正變得越來越復雜。大部分源碼（尤其是各種函數庫和框架）都要經過轉換，才能投入生產環境。
常見的源碼轉換，主要是以下三種情況：
（1）壓縮，減小體積。比如 jQuery 1.9 的源碼，壓縮前是 252KB，壓縮后是 32KB。
（2）多個文件合并，以減少 HTTP 請求數。
（3）其他語言編譯成 JavaScript。最常見的例子就是 CoffeeScript。
</blockquote>這三種情況，都使得實際運行的代碼不同于開發代碼。因此，除錯（debug）變得困難重重。
通常，JavaScript 的解釋器會告訴你，第幾行第幾列代碼出錯。但是，這對于轉換后的代碼毫無用處。舉例來說，jQuery 1.9 壓縮后只有 3 行，每行 3 萬個字符，所有內部變量都改了名字。你看著報錯信息，感到毫無頭緒，根本不知道它所對應的原始位置。
這就是 Source map 想要解決的問題。
二、什么是 Source map
簡單說，Source map 就是一個信息文件，里面儲存著位置信息。也就是說，轉換后的代碼的每一個位置，所對應的轉換前的位置。
有了它，出錯的時候，除錯工具將直接顯示原始代碼，而不是轉換后的代碼。這無疑給開發者帶來了很大方便。
目前，暫時只有 Chrome 瀏覽器支持這個功能。在 Developer Tools 的 Setting 設置中，確認選中"Enable source maps"。
三、如何啟用 Source map
正如前文所提到的，只要在轉換后的代碼尾部，加上一行就可以了。
//@ sourceMappingURL=/path/to/file.js.map
map 文件可以放在網絡上，也可以放在本地文件系統。
四、如何生成 Source map
最常用的方法是使用 Google 的 Closure 編譯器。
生成命令的格式如下：
java -jar compiler.jar \
--js script.js \
--create_source_map ./script-min.js.map \
--source_map_format=V3 \
--js_output_file script-min.js
</blockquote>各個參數的意義如下：
- js： 轉換前的代碼文件
- create_source_map： 生成的 source map 文件
- source_map_format：source map 的版本，目前一律采用 V3。
- js_output_file： 轉換后的代碼文件。
</blockquote>其他的生成文件可以參考這篇文章。
五、Source map 的格式
打開 Source map 文件，它大概是這個樣子：
{
version : 3,
file: "out.js",
sourceRoot : "",
sources: ["foo.js"， "bar.js"],
names: ["src"， "maps"， "are"， "fun"],
mappings: "AAgBC,SAAQ,CAAEA"
}
</blockquote>整個文件就是一個 JavaScript 對象，可以被解釋器讀取。它主要有以下幾個屬性：
- version：Source map 的版本，目前為3。
- file：轉換后的文件名。
- sourceRoot：轉換前的文件所在的目錄。如果與轉換前的文件在同一目錄，該項為空。
- sources：轉換前的文件。該項是一個數組，表示可能存在多個文件合并。
- names：轉換前的所有變量名和屬性名。
- mappings：記錄位置信息的字符串，下文詳細介紹。
</blockquote>六、mappings 屬性
下面才是真正有趣的部分：兩個文件的各個位置是如何一一對應的。
關鍵就是 map 文件的 mappings 屬性。這是一個很長的字符串，它分成三層。
第一層是行對應，以分號（;）表示，每個分號對應轉換后源碼的一行。所以，第一個分號前的內容，就對應源碼的第一行，以此類推。
第二層是位置對應，以逗號（，）表示，每個逗號對應轉換后源碼的一個位置。所以，第一個逗號前的內容，就對應該行源碼的第一個位置，以此類推。
第三層是位置轉換，以 VLQ 編碼表示，代表該位置對應的轉換前的源碼位置。
</blockquote>舉例來說，假定 mappings 屬性的內容如下：
mappings:"AAAAA,BBBBB;CCCCC"
</blockquote>就表示，轉換后的源碼分成兩行，第一行有兩個位置，第二行有一個位置。
七、位置對應的原理
每個位置使用五位，表示五個字段。
從左邊算起，
- 第一位，表示這個位置在（轉換后的代碼的）的第幾列。
- 第二位，表示這個位置屬于 sources 屬性中的哪一個文件。
- 第三位，表示這個位置屬于轉換前代碼的第幾行。
- 第四位，表示這個位置屬于轉換前代碼的第幾列。
- 第五位，表示這個位置屬于 names 屬性中的哪一個變量。
</blockquote>有幾點需要說明。首先，所有的值都是以 0 作為基數的。其次，第五位不是必需的，如果該位置沒有對應 names 屬性中的變量，可以省略第五位。再次，每一位都采用 VLQ 編碼表示；由于 VLQ 編碼是變長的，所以每一位可以由多個字符構成。
舉例來說，如果某個位置的值是 AAAAA，由于A在 VLQ 編碼中表示0，因此這個位置的五個位實際上都是0。它的意思是，該位置在轉換后代碼的第 0 列，對應 sources 屬性中第 0 個文件，屬于轉換前代碼的第 0 行第 0 列，對應 names 屬性中的第 0 個變量。
八、VLQ 編碼
最后，談談如何用 VLQ 編碼表示數值。
這種編碼最早用于 MIDI 文件，后來被多種格式采用。它的特點就是可以非常精簡地表示很大的數值。
VLQ 編碼是變長的。如果（整）數值在-15 到 +15 之間（含兩個端點），用一個字符表示；超出這個范圍，就需要用多個字符表示。它規定，每個字符使用 6 個兩進制位，正好可以借用 Base 64編碼的字符表。
在這 6 個位中，左邊的第一位（最高位）表示是否"連續"（continuation）。如果是1，代表這 ６ 個位后面的 6 個位也屬于同一個數；如果是0，表示該數值到這 6 個位結束。
Continuation
Sign
VV
１０１０１１
</blockquote>這 6 個位中的右邊最后一位（最低位）的含義，取決于這 6 個位是否是某個數值的 VLQ 編碼的第一個字符。如果是的，這個位代表"符號"（sign），0 為正，1 為負（Source map 的符號固定為0）；如果不是，這個位沒有特殊含義，被算作數值的一部分。
九、VLQ 編碼：實例
下面看一個例子，如何對數值 16 進行 VLQ 編碼。
第一步，將 16 改寫成二進制形式 10000。
第二步，在最右邊補充符號位。因為 16 大于0，所以符號位為0，整個數變成 100000。
第三步，從右邊的最低位開始，將整個數每隔 5 位，進行分段，即變成 1 和 00000 兩段。如果最高位所在的段不足 5 位，則前面補0，因此兩段變成 00001 和 00000。
第四步，將兩段的順序倒過來，即 00000 和 00001。
第五步，在每一段的最前面添加一個"連續位"，除了最后一段為0，其他都為1，即變成 100000 和 000001。
第六步，將每一段轉成 Base 64 編碼。
</blockquote>查表可知，100000 為g，000001 為B。因此，數值 16 的 VLQ 編碼為 gB。上面的過程，看上去好像很復雜，做起來其實很簡單，具體的實現請看官方的 base64-vlq.js 文件，里面有詳細的注釋。
十、參考鏈接
- Introduction To JavaScript Source Maps
- Source Map Revision 3 Proposal
來自: 阮一峰的網絡日志
