JavaScript Source Map 詳解

源碼地址： http://www.ruanyifeng.com/blog/2013/01/javascript_source_map.html

上週，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文件，與源碼在同一個目錄下，你能夠點擊進去，看看它的樣子。

這是一個頗有用的功能，本文將詳細講解這個功能。

1、從源碼轉換講起

JavaScript腳本正變得愈來愈複雜。大部分源碼（尤爲是各類函數庫和框架）都要通過轉換，才能投入生產環境。

常見的源碼轉換，主要是如下三種狀況：

　　（1）壓縮，減少體積。好比jQuery 1.9的源碼，壓縮前是252KB，壓縮後是32KB。

　　（2）多個文件合併，減小HTTP請求數。

　　（3）其餘語言編譯成JavaScript。最多見的例子就是CoffeeScript。

這三種狀況，都使得實際運行的代碼不一樣於開發代碼，除錯（debug）變得困難重重。

一般，JavaScript的解釋器會告訴你，第幾行第幾列代碼出錯。可是，這對於轉換後的代碼毫無用處。舉例來講，jQuery 1.9壓縮後只有3行，每行3萬個字符，全部內部變量都改了名字。你看着報錯信息，感到毫無頭緒，根本不知道它所對應的原始位置。

這就是Source map想要解決的問題。

2、什麼是Source map

簡單說，Source map就是一個信息文件，裏面儲存着位置信息。也就是說，轉換後的代碼的每個位置，所對應的轉換前的位置。

有了它，出錯的時候，除錯工具將直接顯示原始代碼，而不是轉換後的代碼。這無疑給開發者帶來了很大方便。

目前，暫時只有Chrome瀏覽器支持這個功能。在Developer Tools的Setting設置中，確認選中"Enable source maps"。

3、如何啓用Source map

正如前文所提到的，只要在轉換後的代碼尾部，加上一行就能夠了。

　　//@ sourceMappingURL=/path/to/file.js.map

map文件能夠放在網絡上，也能夠放在本地文件系統。

4、如何生成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

各個參數的意義以下：

　　- js： 轉換前的代碼文件
　　- create_source_map： 生成的source map文件
　　- source_map_format：source map的版本，目前一概採用V3。
　　- js_output_file： 轉換後的代碼文件。

其餘的生成方法能夠參考這篇文章。

5、Source map的格式

打開Source map文件，它大概是這個樣子：

　　{
　　　　version : 3,
　　　　file: "out.js",
　　　　sourceRoot : "",
　　　　sources: ["foo.js", "bar.js"],
　　　　names: ["src", "maps", "are", "fun"],
　　　　mappings: "AAgBC,SAAQ,CAAEA"
　　}

整個文件就是一個JavaScript對象，能夠被解釋器讀取。它主要有如下幾個屬性：

　　- version：Source map的版本，目前爲3。

　　- file：轉換後的文件名。

　　- sourceRoot：轉換前的文件所在的目錄。若是與轉換前的文件在同一目錄，該項爲空。

　　- sources：轉換前的文件。該項是一個數組，表示可能存在多個文件合併。

　　- names：轉換前的全部變量名和屬性名。

　　- mappings：記錄位置信息的字符串，下文詳細介紹。

6、mappings屬性

下面纔是真正有趣的部分：兩個文件的各個位置是如何一一對應的。

關鍵就是map文件的mappings屬性。這是一個很長的字符串，它分紅三層。

　　第一層是行對應，以分號（;）表示，每一個分號對應轉換後源碼的一行。因此，第一個分號前的內容，就對應源碼的第一行，以此類推。

　　第二層是位置對應，以逗號（,）表示，每一個逗號對應轉換後源碼的一個位置。因此，第一個逗號前的內容，就對應該行源碼的第一個位置，以此類推。

　　第三層是位置轉換，以VLQ編碼表示，表明該位置對應的轉換前的源碼位置。

舉例來講，假定mappings屬性的內容以下：

　　mappings:"AAAAA,BBBBB;CCCCC"

就表示，轉換後的源碼分紅兩行，第一行有兩個位置，第二行有一個位置。

7、位置對應的原理

每一個位置使用五位，表示五個字段。

從左邊算起，

　　- 第一位，表示這個位置在（轉換後的代碼的）的第幾列。

　　- 第二位，表示這個位置屬於sources屬性中的哪個文件。

　　- 第三位，表示這個位置屬於轉換前代碼的第幾行。

　　- 第四位，表示這個位置屬於轉換前代碼的第幾列。

　　- 第五位，表示這個位置屬於names屬性中的哪個變量。

有幾點須要說明。首先，全部的值都是以0做爲基數的。其次，第五位不是必需的，若是該位置沒有對應names屬性中的變量，能夠省略第五位。再次，每一位都採用VLQ編碼表示；因爲VLQ編碼是變長的，因此每一位能夠由多個字符構成。

若是某個位置是AAAAA，因爲A在VLQ編碼中表示0，所以這個位置的五個位實際上都是0。它的意思是，該位置在轉換後代碼的第0列，對應sources屬性中第0個文件，屬於轉換前代碼的第0行第0列，對應names屬性中的第0個變量。

8、VLQ編碼

最後，談談如何用VLQ編碼表示數值。

這種編碼最先用於MIDI文件，後來被多種格式採用。它的特色就是能夠很是精簡地表示很大的數值。

VLQ編碼是變長的。若是（整）數值在-15到+15之間（含兩個端點），用一個字符表示；超出這個範圍，就須要用多個字符表示。它規定，每一個字符使用6個兩進制位，正好能夠借用Base 64編碼的字符表。

在這6個位中，左邊的第一位（最高位）表示是否"連續"（continuation）。若是是1，表明這６個位後面的6個位也屬於同一個數；若是是0，表示該數值到這6個位結束。

　　Continuation
　　|　　　　　Sign
　　|　　　　　|
　　V　　　　　V
　　１０１０１１

這6個位中的右邊最後一位（最低位）的含義，取決於這6個位是不是某個數值的VLQ編碼的第一個字符。若是是的，這個位表明"符號"（sign），0爲正，1爲負（Source map的符號固定爲0）；若是不是，這個位沒有特殊含義，被算做數值的一部分。

9、VLQ編碼：實例

下面看一個例子，如何對數值16進行VLQ編碼。

　　第一步，將16改寫成二進制形式10000。

　　第二步，在最右邊補充符號位。由於16大於0，因此符號位爲0，整個數變成100000。

　　第三步，從右邊的最低位開始，將整個數每隔5位，進行分段，即變成1和00000兩段。若是最高位所在的段不足5位，則前面補0，所以兩段變成00001和00000。

　　第四步，將兩段的順序倒過來，即00000和00001。

　　第五步，在每一段的最前面添加一個"連續位"，除了最後一段爲0，其餘都爲1，即變成100000和000001。

　　第六步，將每一段轉成Base 64編碼。

查表可知，100000爲g，000001爲B。所以，數值16的VLQ編碼爲gB。上面的過程，看上去好像很複雜，作起來其實很簡單，具體的實現請看官方的base64-vlq.js文件，裏面有詳細的註釋。

10、參考連接

　　- Introduction To JavaScript Source Maps
　　- Source Map Revision 3 Proposal

（完）