[TOC] ## 概述 隨著JavaScript腳本變得越來越復雜，大部分源碼（尤其是各種函數庫和框架）都要經過轉換，才能投入生產環境。 常見的源碼轉換，主要是以下三種情況： * 壓縮，減小體積。比如jQuery 1.9的源碼，壓縮前是252KB，壓縮后是32KB。 * 多個文件合并，減少HTTP請求數。 * 其他語言編譯成JavaScript。最常見的例子就是CoffeeScript。 這三種情況，都使得實際運行的代碼不同于開發代碼，除錯（debug）變得困難重重。 通常，JavaScript的解釋器會告訴你，第幾行第幾列代碼出錯。但是，這對于轉換后的代碼毫無用處。舉例來說，jQuery 1.9壓縮后只有3行，每行3萬個字符，所有內部變量都改了名字。你看著報錯信息，感到毫無頭緒，根本不知道它所對應的原始位置。 這就是Source map想要解決的問題。 簡單說，Source map就是一個信息文件，里面儲存著位置信息。也就是說，轉換后的代碼的每一個位置，所對應的轉換前的位置。 有了它，出錯的時候，除錯工具將直接顯示原始代碼，而不是轉換后的代碼。這無疑給開發者帶來了很大方便。 目前，暫時只有Chrome瀏覽器支持這個功能。在Developer Tools的Setting設置中，確認選中"Enable source maps"。 ## 生成和啟用 生成Source Map的最常用方法，是使用Google的[Closure編譯器](https://developers.google.com/closure/compiler/)。 生成命令的格式如下： ~~~ 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： 轉換后的代碼文件。 其他的生成方法可以參考[這篇文章](http://net.tutsplus.com/tutorials/tools-and-tips/source-maps-101/)。 啟用Source map的方法很簡單，只要在轉換后的代碼頭部或尾部，加上一行就可以了。 ~~~ //# sourceMappingURL=/path/to/file.js.map ~~~ 或者 ~~~ /*# sourceMappingURL=/path/to/file.js.map */ ~~~ 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：記錄位置信息的字符串。 ## mappings屬性 轉換前后的代碼一一對應的關鍵，就是map文件的mappings屬性。這是一個很長的字符串，它分成三層。 第一層是行對應，以分號（;）表示，每個分號對應轉換后源碼的一行。所以，第一個分號前的內容，就對應源碼的第一行，以此類推。 第二層是位置對應，以逗號（,）表示，每個逗號對應轉換后源碼的一個位置。所以，第一個逗號前的內容，就對應該行源碼的第一個位置，以此類推。 第三層是位置轉換，以[VLQ編碼](http://en.wikipedia.org/wiki/Variable-length_quantity)表示，代表該位置對應的轉換前的源碼位置。 舉例來說，假定mappings屬性的內容如下： ~~~ mappings:"AAAAA,BBBBB;CCCCC" ~~~ 它表示，轉換后的源碼分成兩行，第一行有兩個位置，第二行有一個位置。 每個位置使用五位，表示五個字段。從左邊算起， * 第一位，表示這個位置在（轉換后的代碼的）的第幾列。 * 第二位，表示這個位置屬于sources屬性中的哪一個文件。 * 第三位，表示這個位置屬于轉換前代碼的第幾行。 * 第四位，表示這個位置屬于轉換前代碼的第幾列。 * 第五位，表示這個位置屬于names屬性中的哪一個變量。 有幾點需要說明。首先，所有的值都是以0作為基數的。其次，第五位不是必需的，如果該位置沒有對應names屬性中的變量，可以省略第五位。再次，每一位都采用VLQ編碼表示；由于VLQ編碼是變長的，所以每一位可以由多個字符構成。 如果某個位置是AAAAA，由于A在VLQ編碼中表示0，因此這個位置的五個位實際上都是0。它的意思是，該位置在轉換后代碼的第0列，對應sources屬性中第0個文件，屬于轉換前代碼的第0行第0列，對應names屬性中的第0個變量。 ## VLQ編碼 這種編碼最早用于MIDI文件，后來被多種格式采用。它的特點就是可以非常精簡地表示很大的數值。 VLQ編碼是變長的。如果（整）數值在-15到+15之間（含兩個端點），用一個字符表示；超出這個范圍，就需要用多個字符表示。它規定，每個字符使用6個兩進制位，正好可以借用[Base 64編碼](http://en.wikipedia.org/wiki/Base_64)的字符表。 在這6個位中，左邊的第一位（最高位）表示是否"連續"（continuation）。如果是1，代表這６個位后面的6個位也屬于同一個數；如果是0，表示該數值到這6個位結束。 這6個位中的右邊最后一位（最低位）的含義，取決于這6個位是否是某個數值的VLQ編碼的第一個字符。如果是的，這個位代表"符號"（sign），0為正，1為負（Source map的符號固定為0）；如果不是，這個位沒有特殊含義，被算作數值的一部分。 ~~~ Continuation |　　　　　Sign |　　　　　| V　　　　　V １０１０１１ ~~~ 下面舉例如何對數值16進行VLQ編碼。 (1) 將16改寫成二進制形式10000。 (2) 在最右邊補充符號位。因為16大于0，所以符號位為0，整個數變成100000。 (3) 從右邊的最低位開始，將整個數每隔5位，進行分段，即變成1和00000兩段。如果最高位所在的段不足5位，則前面補0，因此兩段變成00001和00000。 (4) 將兩段的順序倒過來，即00000和00001。 (5) 在每一段的最前面添加一個"連續位"，除了最后一段為0，其他都為1，即變成100000和000001。 (6) 將每一段轉成Base 64編碼。查表可知，100000為g，000001為B。因此，數值16的VLQ編碼為gB。 上面的過程，看上去好像很復雜，做起來其實很簡單，具體的實現可以參考官方的[base64-vlq.js](https://github.com/mozilla/source-map/blob/master/lib/source-map/base64-vlq.js)文件，里面有詳細的注釋。 ## 參考鏈接 * [Introduction To JavaScript Source Maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/) * [Source Map Revision 3 Proposal](https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit) * Paul Irish,?[sourceMappingURL and sourceURL syntax changed](http://updates.html5rocks.com/2013/06/sourceMappingURL-and-sourceURL-syntax-changed)