SourceMap 與前端異常監(jiān)控
?? 加個(gè)關(guān)注，后續(xù)上新不錯(cuò)過(guò)~
背景
我們從事 Web 開(kāi)發(fā)工作中，異常監(jiān)控系統(tǒng)已經(jīng)是我們朝夕相處的好助手，但是這些異常處理工具通常都是建立在 Web 生態(tài)，或者是假定運(yùn)行在瀏覽器環(huán)境下的，但是當(dāng)我們需要給一套跨端系統(tǒng)搭建一套類似的異常監(jiān)控系統(tǒng)，并且期望該系統(tǒng)兼容 Web 生態(tài)，現(xiàn)有的工具很可能就不滿足我們的需求了，因此我們需要考慮一套完整的異常監(jiān)控系統(tǒng)整個(gè)鏈路將會(huì)涉及到哪些工具鏈，以及如何修改這些工具鏈來(lái)適配我們的跨端系統(tǒng)。
精彩的一天從查 Bug 開(kāi)始
我們先從和我們程序員最息息相關(guān)的線上查 Bug 開(kāi)始。
下面這種圖，相信大家很多人都很熟悉，當(dāng)我們收到線上 Bug 反饋或者收到報(bào)警電話時(shí)，第一時(shí)間基本就是去自己的監(jiān)控平臺(tái)去查看線上日志，大家很可能看到類似下面這張截圖
有經(jīng)驗(yàn)的老司機(jī)，立馬就可以定位到自己代碼里哪里出了問(wèn)題，但是有沒(méi)有仔細(xì)思考過(guò)整套監(jiān)控系統(tǒng)是如何打通的呢？或者說(shuō)如果有一天你的監(jiān)控系統(tǒng)出了問(wèn)題，你知道如何追查是哪個(gè)環(huán)節(jié)出了問(wèn)題嗎？
代碼反解
有經(jīng)驗(yàn)的老司機(jī)立馬就反應(yīng)過(guò)來(lái)了，不就是代碼里集成下 Sentry 的 Client，然后每次把 SourceMap 也上傳一份給 Sentry，線上遇到錯(cuò)誤將錯(cuò)誤上傳給 Sentry Server，Sentry Server基于錯(cuò)誤堆棧和 SourceMap 反解出原始的堆棧就可以了。是的，監(jiān)控系統(tǒng)要解決的一個(gè)核心問(wèn)題就是代碼反解。
出于一些性能和安全等的考慮，通常我們發(fā)布到線上的代碼，通常并非原始的代碼，而是經(jīng)過(guò)混淆壓縮后的代碼，即使不經(jīng)過(guò)壓縮，大部分的前端工程都會(huì)經(jīng)過(guò)一個(gè) build 的過(guò)程，這個(gè)過(guò)程里通常會(huì)包括代碼的轉(zhuǎn)換、打包和壓縮等，這使得調(diào)試生成的代碼變得異常困難，因此，我們需要一個(gè)工具幫我們解決這類調(diào)試問(wèn)題。
SourceMap
SourceMap 幾乎完美的解決了代碼反解問(wèn)題，其使用方式十分簡(jiǎn)單，我們?cè)诰幾g的時(shí)候除了生成最終產(chǎn)物 xxx.js 文件外還會(huì)額外生成一個(gè) xxx.js.map 的文件，這個(gè) map 文件里包含了原始代碼及其位置映射信息，這樣我們利用 xxx.js 和 xxx.js.map 就可以將 xxx.js 的代碼及其位置完美的映射會(huì)源代碼以及位置，這樣我們的調(diào)試工具就可以基于這個(gè) map 文件實(shí)現(xiàn)源碼調(diào)試了。其原理雖然很簡(jiǎn)單，但是當(dāng)我們?cè)诠こ讨袑?shí)際應(yīng)用 SourceMap 的時(shí)候，仍然會(huì)碰到這樣或那樣的問(wèn)題。一個(gè)很常見(jiàn)的問(wèn)題就是，為啥用戶上報(bào)的錯(cuò)誤沒(méi)法反解為原始代碼的錯(cuò)誤堆棧了？
SourceMap 支持的全鏈路流程
SourceMap 的使用并非是簡(jiǎn)單的一個(gè)編譯生成即可，其實(shí)際上是需要我們整個(gè)的工作鏈路進(jìn)行配合，才能使得 SourceMap 可以正常工作，因此我們需要先看看我們的整個(gè)工作鏈路上哪些環(huán)節(jié)會(huì)涉及 SourceMap，以及可能會(huì)碰到哪些問(wèn)題。
以一個(gè)業(yè)務(wù)場(chǎng)景為例，我們用 Vue 開(kāi)發(fā)的應(yīng)用部署到線上 -> 發(fā)生了異常 -> 上報(bào)到了 Sentry -> Sentry 幫我們將錯(cuò)誤進(jìn)行反解展示給我們。這個(gè)業(yè)務(wù)場(chǎng)景非常簡(jiǎn)單但是實(shí)際涉及到了很多 SourceMap 的處理。
Transformer
首先我們需要我們的 DSL Transformer 支持 SourceMap
// App.vue
<template>
<div></div>
</template>
<script lang="ts">
let x: 10;
export default {}
</script>
<style>
h1 {
color: red;
}
</style>
<i18n>
{ "greeting": "hello" }
</i18n>
我們使用 @vue/compiler-sfc 將該 Vue 文件編譯為一個(gè) SFCRecord，此時(shí) SFCRecord 里實(shí)際上包含了每個(gè) block 的 SourceMap
const { parse } = require('@vue/compiler-sfc');
const fs = require('fs');
const path = require('path');
async function main(){
const content = fs.readFileSync(path.join(__dirname, './App.vue'),'utf-8');
const sfcRecord = parse(content);
const map = sfcRecord.descriptor['styles'][0].map
console.log('sfc:',map) // 打印style的SourceMap
}
main();
我們可以進(jìn)一步的根據(jù)每個(gè) block 的 tag 和 lang 來(lái)繼續(xù) transform 每個(gè) block，如使用 Babel | Typescript 處理 Script，PostCSS來(lái)處理 Style，Pug 來(lái)處理 Template，這里每個(gè) Transformer 也都需要處理 SourceMap。
Bundler
處理完 Vue 文件的編譯后，我們希望通過(guò)一個(gè) bundler 來(lái)處理 Vue 模塊的打包，此時(shí)我們可以使用esbuild、rollup、或者 Webpack，我們這里使用 rollup-plugin-vue 來(lái)配合 rollup 給 Vue 應(yīng)用進(jìn)行打包。
async function bundle(){
const bundle = await rollup.rollup({
input: [path.join(__dirname, './App.vue')],
plugins:[rollupPluginVue({needMap:true})],
external: ['vue'],
output: {
sourcemap:'inline'
}
})
const result = await bundle.write({
output: {
file: 'bundle.js',
sourcemap:true
},
})
for(const chunk of result.output){
console.log('chunk:',chunk.map) // SourceMap
}
}
bundle()
因此這里也需要 bundle 在進(jìn)行 bundler 的過(guò)程中同時(shí)處理生成 sourcemap。
Minifier
但我們 bundler 完代碼后，還需要將代碼進(jìn)行壓縮混淆才能發(fā)布到線上，這時(shí)我們需要使用 minify 工具進(jìn)行混淆壓縮。我們使用 terser 進(jìn)行壓縮。壓縮時(shí)不僅需要處理 minfy 過(guò)程生成的 SourceMap 還需要處理其和原始 bundler 生成的 SourceMap 合并的問(wèn)題，否則 SourceMap 和經(jīng)過(guò)壓縮處理的代碼對(duì)應(yīng)不上了。
for(const chunk of result.output){
console.log('chunk:', chunk.map)
const minifyResult = await require('terser').minify(chunk.code, {
sourceMap:true,
})
console.log('minifyMap:', minifyResult.map)
}
Runtime
經(jīng)過(guò)一番折騰，我們的編譯流程終于處理完 SourceMap 了，我們開(kāi)發(fā)過(guò)程中突然發(fā)現(xiàn)了代碼出問(wèn)題了，我們希望錯(cuò)誤的堆棧能顯示源碼的位置，另外能支持源碼調(diào)試應(yīng)用，這時(shí)候就需要用的瀏覽器的 SourceMap 支持和 node 的 SourceMap 支持了。
日志收集和上報(bào)
經(jīng)過(guò)一番眼花繚亂的操作，我們的代碼終于和 SourceMap 對(duì)應(yīng)上了，我們平穩(wěn)的將業(yè)務(wù)部署上線，上線前我們需要確保我們的錯(cuò)誤能夠以正確的格式上報(bào)到我們的日志平臺(tái)，然而我們線上運(yùn)行的平臺(tái)那么多樣，運(yùn)行的 JS 引擎也是各式各樣，我們需要將用戶的錯(cuò)誤統(tǒng)一成一個(gè)格式上報(bào)給平臺(tái)，幸運(yùn)的是 Sentry 的客戶端已經(jīng)幫我們做了這件事情。我們只需要考慮接入 Sentry 的客戶端就行了。因?yàn)槿绻苯訉?SourceMap 一起跟隨 js 代碼下發(fā)，這就導(dǎo)致用戶可以直接窺探你的源碼了，類似發(fā)生這樣的事情就很尷尬了https://zhuanlan.zhihu.com/p/26033573，因此我們還需要考慮將 SourceMap 發(fā)布到內(nèi)網(wǎng)而非公網(wǎng)上，這時(shí)就需要處理 SourceMap 關(guān)聯(lián)的問(wèn)題了。
錯(cuò)誤日志反解
一切都妥當(dāng)了，只需要等用戶的錯(cuò)誤上報(bào)上來(lái)（最好永遠(yuǎn)別來(lái)），我就可以在 Sentry 上查看用戶的原始錯(cuò)誤堆棧，幫用戶排查問(wèn)題了，這時(shí)候?qū)嶋H上 Sentry Server 端偷偷幫我們做了根據(jù)用戶的錯(cuò)誤棧和用戶的 SourceMap，幫我們反解錯(cuò)誤棧的事情了。
總結(jié)一下，一個(gè)完整的 SourceMap 流程支持包括了如下這些步驟：
transformer: Babel、typescript、emscripten 、 esbuild minifier: esbuild ,terser bundler: esbuild, webpack, rollup runtime: browser & node & deno 日志上報(bào): sentry client 錯(cuò)誤日志反解: sentry server && node-sourcemap-support
上面這些流程，基本上大多數(shù)工具都幫我們封裝好了，我們只需要安心使用即可，但是當(dāng)某天你需要自己開(kāi)發(fā)一個(gè)自定義的 DSL 的 transformer 通過(guò)自研的 bundler 進(jìn)行編譯打包，運(yùn)行在自研的 JS 引擎上并且使用自研的 monitor client 上報(bào)到自研的 apm 平臺(tái)上，任何環(huán)節(jié)的出錯(cuò)都可能導(dǎo)致你線上的錯(cuò)誤日志反解前功盡棄，你所能做的就是在整個(gè)鏈路上進(jìn)行分析定位。
我們接下來(lái)就看看整個(gè)鏈路上有多少種出錯(cuò)的風(fēng)險(xiǎn)和可能，并且如何定位修復(fù)這些問(wèn)題。
SourceMap 格式
首先我們需要了解下 SourceMap 的基本格式
我們將一個(gè) .ts 文件編譯為 .js 文件，看看其 SourceMap 信息是如何處理映射的。我們項(xiàng)目包含了原始的 ts 文件 add.ts、編譯后的產(chǎn)物文件 add.js 和 SourceMap 文件 add.js.map，其內(nèi)容如下
add.ts
const add = (x:number, y:number) => {
return x + y;
}
add.js
var add = function (x, y) {
return x + y;
};
//# sourceMappingURL=module.js.map
SourceMap 的規(guī)范本身十分精簡(jiǎn)和清晰，其本身是一個(gè) JSON 文件，包含如下幾個(gè)核心字段
{
version : 3, // SourceMap標(biāo)準(zhǔn)版本,最新的為3
file: "add.js", // 轉(zhuǎn)換后的文件名
sourceRoot : "", // 轉(zhuǎn)換前的文件所在目錄，如果與轉(zhuǎn)換前的文件在同一目錄，該項(xiàng)為空
sources: ["add.ts"], // 轉(zhuǎn)換前的文件，該項(xiàng)是一個(gè)數(shù)組，表示可能存在多個(gè)文件合并
names: [], // 轉(zhuǎn)換前的所有變量名和屬性名,多用于minify的場(chǎng)景
sourcesContent: [ // 原始文件內(nèi)容
"const add = (x:number,y:number) => {\n return x+y;\n}"
]
mappings: "AAAA,IAAM,GAAG,GAAG,UAAC,CAAQ,EAAC,CAAQ;IAC5B,OAAO,CAAC,GAAC,CAAC,CAAC;AACb,CAAC,CAAA",
}
簡(jiǎn)單介紹下 mapping 的格式，mapping 實(shí)際上是個(gè)三級(jí)結(jié)構(gòu)，我們以上述的例子為例
line：每個(gè) mapping 包含由 ;分割的多行內(nèi)容
lines = mappings.split(';')
// [
'AAAA,IAAM,GAAG,GAAG,UAAC,CAAQ,EAAC,CAAQ', // var add = function (x, y) {
'IAC5B,OAAO,CAAC,GAAC,CAAC,CAAC', // return x + y;
'AACb,CAAC,CAAA' // };
]
其中每一行都對(duì)應(yīng)生成代碼的每行文件的位置映射信息，這里的三行分別對(duì)應(yīng)了編譯產(chǎn)物的三行信息
segment：每一行同包含由 ,分割的多個(gè) segment 信息，其中每個(gè) segment 都對(duì)應(yīng)了產(chǎn)物里每一行里每一個(gè)符合所在的列的信息
const segments = lines.map(x => {
return x.split(',')
})
console.log('segments:',segments)
// [
[
'AAAA', 'IAAM',
'GAAG', 'GAAG',
'UAAC', 'CAAQ',
'EAAC', 'CAAQ'
],
[ 'IAC5B', 'OAAO', 'CAAC', 'GAAC', 'CAAC', 'CAAC' ],
[ 'AACb', 'CAAC', 'CAAA' ]
]
fields：每個(gè) segment 實(shí)際上又包含了幾個(gè) field，每個(gè) field 都編碼了具體的行列映射信息,依次為 第一位: 轉(zhuǎn)換后代碼所處的列號(hào)，如果這是當(dāng)前行的第一個(gè) segment，那么是個(gè)絕對(duì)值，否則是相對(duì)于上一個(gè) segment 的相對(duì)值 第二位：表示這個(gè)位置屬于 sources 屬性中的哪一個(gè)文件，相對(duì)于前一個(gè) segment 的位置（區(qū)別于列號(hào)，下一行的第一個(gè) segment 仍然是相對(duì)于上一行的最后一個(gè) segment，并不會(huì) reset） 第三位：表示這個(gè)位置屬于轉(zhuǎn)換前代碼的第幾行，相對(duì)位置，同第二列 第四位：表示這個(gè)位置屬于轉(zhuǎn)換前代碼的第幾列，相對(duì)位置，同第二列 第五位：表示這個(gè)位置屬于 names 屬性中的哪一個(gè)變量,相對(duì)位置，同第二列
這里 field 存儲(chǔ)的值并非是直接的數(shù)字值，而是將數(shù)字使用 vlq 進(jìn)行了編碼，根據(jù)上述這些信息我們實(shí)際上就可以實(shí)現(xiàn) SourceMap 的雙向映射了，即可以根據(jù) SourceMap 和原始代碼的位置信息查找到生成代碼的信息，也可以根據(jù) SourceMap 和生成代碼的位置信息，查找到原始代碼的信息。接下來(lái)我們就實(shí)踐下如何進(jìn)行代碼位置的雙向查找。
雙向查找流程
vlq 解碼
首先第一步我們需要將 vlq 編碼的 SourceMap 反解為原始的數(shù)字偏移信息,我們可以直接使用封裝好的 vlq 庫(kù)完成這一步
function decode() {
const { decode} = require('vlq')
const mappings = JSON.parse(result.sourceMapText).mappings;
console.log('mappings:', mappings)
/**
* @type {string[]}
*/
const lines = mappings.split(';');
const decodeLines = lines.map(line => {
const segments = line.split(',');
const decodedSeg = segments.map(x => {
return decode(x)
})
return decodedSeg;
})
console.log(decodeLines)
}
此時(shí)我們得到一個(gè)解碼后的位置信息
[
[
[ 0, 0, 0, 0 ],
[ 4, 0, 0, 6 ],
[ 3, 0, 0, 3 ],
[ 3, 0, 0, 3 ],
[ 10, 0, 0, 1 ],
[ 1, 0, 0, 8 ],
[ 2, 0, 0, 1 ],
[ 1, 0, 0, 8 ]
],
[
[ 4, 0, 1, -28 ],
[ 7, 0, 0, 7 ],
[ 1, 0, 0, 1 ],
[ 3, 0, 0, 1 ],
[ 1, 0, 0, 1 ],
[ 1, 0, 0, 1 ]
],
[ [ 0, 0, 1, -13 ], [ 1, 0, 0, 1 ], [ 1, 0, 0, 0 ] ]
]
還原絕對(duì)位置索引
此時(shí)的這些位置信息都是相對(duì)位置，我們需要將其還原為絕對(duì)位置
const decoded = decodeLines.map((line) => {
absSegment[0] = 0; // 每行的第一個(gè)segment的位置要重置
if (line.length == 0) {
return [];
}
const absoluteSegment = line.map((segment) => {
const result = [];
for (let i = 0; i < segment.length; i++) {
absSegment[i] += segment[i];
result.push(absSegment[i]);
}
return result;
});
return absoluteSegment;
});
console.log('decoded:', decoded)
}
結(jié)果如下，此時(shí)為絕對(duì)位置映射表
[
[
[ 0, 0, 0, 0 ],
[ 4, 0, 0, 6 ],
[ 7, 0, 0, 9 ],
[ 10, 0, 0, 12 ],
[ 20, 0, 0, 13 ],
[ 21, 0, 0, 21 ],
[ 23, 0, 0, 22 ],
[ 24, 0, 0, 30 ]
],
[
[ 4, 0, 1, 2 ],
[ 11, 0, 1, 9 ],
[ 12, 0, 1, 10 ],
[ 15, 0, 1, 11 ],
[ 16, 0, 1, 12 ],
[ 17, 0, 1, 13 ]
],
[ [ 0, 0, 2, 0 ], [ 1, 0, 2, 1 ], [ 2, 0, 2, 1 ] ]
]
雙向映射
有了這個(gè)絕對(duì)位置映射，我們就可以構(gòu)建源碼和產(chǎn)物的雙向映射了。我們可以實(shí)現(xiàn)兩個(gè)核心 API
originalPositionFor 用于根據(jù)產(chǎn)物的行列號(hào)，查找對(duì)應(yīng)源碼的信息，而generatedPositionFor 則是根據(jù)源碼的文件名、行列號(hào)，查找產(chǎn)物里的位置信息。
class SourceMap {
constructor(rawMap) {
this.decode(rawMap);
this.rawMap = rawMap
}
/**
*
* @param {number} line
* @param {number} column
*/
originalPositionFor(line, column){
const lineInfo = this.decoded[line];
if(!lineInfo){
throw new Error(`不存在該行信息:${line}`);
}
const columnInfo = lineInfo[column];
for(const seg of lineInfo){
// 列號(hào)匹配
if(seg[0] === column){
const [column, sourceIdx,origLine, origColumn] = seg;
const source = this.rawMap.sources[sourceIdx]
const sourceContent = this.rawMap.sourcesContent[sourceIdx];
const result = codeFrameColumns(sourceContent, {
start: {
line: origLine+1,
column: origColumn+1
}
}, {forceColor:true})
return {
source,
line: origLine,
column: origColumn,
frame: result
}
}
}
throw new Error(`不存在該行列號(hào)信息:${line},${column}`)
}
decode(rawMap) {
const {mappings} = rawMap
const { decode } = require('vlq');
console.log('mappings:', mappings);
/**
* @type {string[]}
*/
const lines = mappings.split(';');
const decodeLines = lines.map((line) => {
const segments = line.split(',');
const decodedSeg = segments.map((x) => {
return decode(x);
});
return decodedSeg;
});
const absSegment = [0, 0, 0, 0, 0];
const decoded = decodeLines.map((line) => {
absSegment[0] = 0; // 每行的第一個(gè)segment的位置要重置
if (line.length == 0) {
return [];
}
const absoluteSegment = line.map((segment) => {
const result = [];
for (let i = 0; i < segment.length; i++) {
absSegment[i] += segment[i];
result.push(absSegment[i]);
}
return result;
});
return absoluteSegment;
});
this.decoded = decoded;
}
}
const consumer = new SourceMap(rawMap);
console.log(consumer.originalPositionFor(0,21).frame)
我們還可以使用 codeFrame 直接可視化查找出源碼的上下文信息
generatedPositionFor 的實(shí)現(xiàn)原理類似，不再贅述。
事實(shí)上上面這些反解流程并不需要我們自己去實(shí)現(xiàn)，https://github.com/mozilla/source-map 已經(jīng)幫我們提供了很多的編譯方法，包括不限于
originalPositionFor：查找源碼位置
generatedPositionFor：查找生成代碼位置
eachMapping：生成每個(gè) segment 的詳細(xì)映射信息
Mapping {
generatedLine: 2,
generatedColumn: 17,
lastGeneratedColumn: null,
source: 'add.ts',
originalLine: 2,
originalColumn: 13,
name: null
}
Mapping {
generatedLine: 3,
generatedColumn: 0,
lastGeneratedColumn: null,
source: 'add.ts',
originalLine: 3,
originalColumn: 0,
name: null
}
Mapping {
generatedLine: 3,
generatedColumn: 1,
lastGeneratedColumn: null,
source: 'add.ts',
originalLine: 3,
originalColumn: 1,
name: null
}
Mapping {
generatedLine: 3,
generatedColumn: 2,
lastGeneratedColumn: null,
source: 'add.ts',
originalLine: 3,
originalColumn: 1,
name: null
}
事實(shí)上 Sentry 的 SourceMap 反解功能也是基于此實(shí)現(xiàn)的。
SourceMap 全鏈路支持
前面我們已經(jīng)介紹的 SourceMap 的基本格式，以及如何基于 SourceMap 的內(nèi)容，來(lái)實(shí)現(xiàn) SourceMap 的雙向查找功能，大部分的 sourcmap 相應(yīng)的工具鏈都是基于此設(shè)計(jì)的，但是在給整個(gè)鏈路做 SourceMap 支持的時(shí)候，但是鏈路的每一步需要解決的問(wèn)題卻各有不同（的坑），我們來(lái)一步步的研（踩）究（坑）吧。
給 transformer 添加 SourceMap 映射
Web 社區(qū)的主流語(yǔ)言的工具鏈都已經(jīng)有了內(nèi)置的 SourceMap 支持了，但是如果你自行設(shè)計(jì)一個(gè) DSL 要怎么給其添加 SourceMap 支持呢？事實(shí)上 SourceMapGenerator 給我們提供了便捷的生成 SourceMap 內(nèi)容的方法，但是當(dāng)我們處理各種字符串變換的時(shí)候，直接使用其 API 仍然較為繁瑣。幸運(yùn)的是很多工具封裝了生成 SourceMap 的操作，提供了較為上層的 api。我們自己實(shí)現(xiàn) transformer 主要分為兩種場(chǎng)景，一種是基于 AST 的變換，另一種則是對(duì)字符串（可能壓根不存在 AST）的增刪改查。
AST 變換
大部分的前端 transform 工具，都內(nèi)置幫我們處理好了 SourceMap 的映射，我們只需要關(guān)心如何處理 AST 即可，以 babel 為例，并不需要我們手動(dòng)的進(jìn)行 SourceMap 節(jié)點(diǎn)的操作
import babel from '@babel/core';
import fs from 'fs';
const result = babel.transform('a === b;', {
sourceMaps: true,
filename: 'transform.js',
plugins: [
{
name: 'my-plugin',
pre: () => {
console.log('xx');
},
visitor: {
BinaryExpression(path, t) {
let tmp = path.node.left;
path.node.left = path.node.right;
path.node.right = tmp;
}
}
}
]
});
console.log(result.code, result.map);
// 結(jié)果
b === a;
{
version: 3,
sources: [ 'transform.js' ],
names: [ 'b', 'a' ],
mappings: 'AAAMA,CAAN,KAAAC,CAAC',
sourcesContent: [ 'a === b;' ]
}
但是 AST 并不能覆蓋所有場(chǎng)景，例如我們?nèi)绻枰獙?c++ 或者 brainfuck 編譯為 js，就很難找到便捷的工具，或者我們只需要替換代碼里的部分內(nèi)容，AST 分析就是大才小用了。此時(shí)我們可以使用 magic-string 來(lái)實(shí)現(xiàn)。
const MagicString = require('magic-string');
const s = new MagicString('problems = 99');
s.overwrite(0, 8, 'answer');
s.toString(); // 'answer = 99'
s.overwrite(11, 13, '42'); // character indices always refer to the original string
s.toString(); // 'answer = 42'
s.prepend('var ').append(';'); // most methods are chainable
s.toString(); // 'var answer = 42;'
const map = s.generateMap({
source: 'source.js',
file: 'converted.js.map',
includeContent: true
}); // generates a v3 SourceMap
console.log('code:', s.toString());
console.log('map:', map);
// 結(jié)果
code: var answer = 42;
map: SourceMap {
version: 3,
file: 'converted.js.map',
sources: [ 'source.js' ],
sourcesContent: [ 'problems = 99' ],
names: [],
mappings: 'IAAA,MAAQ,GAAG'
}
我們發(fā)現(xiàn)對(duì)于簡(jiǎn)單的字符串處理，magic-string 比使用 AST 的方式要方便和高效很多。
SourceMap 驗(yàn)證
當(dāng)我們給我們的 transformer 加了 SourceMap 支持后，我們?cè)趺打?yàn)證我們的 SourceMap 是正確的呢？你除了可以使用上面提到的 SourceMap 庫(kù)的雙向反解功能進(jìn)行驗(yàn)證外，一個(gè)可視化的驗(yàn)證工具將大大簡(jiǎn)化我們的工作。esbuild 作者就開(kāi)發(fā)了一個(gè) SourceMap 可視化驗(yàn)證的網(wǎng)站 https://evanw.github.io/source-map-visualization/ 來(lái)幫我們簡(jiǎn)化 SourceMap 的驗(yàn)證工作。
SourceMap 合并
當(dāng)我們處理好 transformer 的 SourceMap 生成之后，接下來(lái)就需要將 transformer 接入到 bundler 了，一定意義上 bundler 也可以視為一種 transformer，只是此時(shí)其輸入不再是單個(gè)源文件而是多個(gè)源文件。但這里牽扯到的一個(gè)問(wèn)題是將 A 進(jìn)行編譯生成了 B with SourceMap1 接著又將 B 進(jìn)一步進(jìn)行編譯生成了 C with SourceMap2，那么我們?nèi)绾胃鶕?jù) C 反解到 A 呢？很明顯使用 SourceMap2 只能幫助我們將 C 反解到 B，并不能反解到 A，大部分的反解工具也不支持自動(dòng)級(jí)聯(lián)反解，因此當(dāng)我們將 B 生成 C 的時(shí)候，還需要考慮將 SourceMap1 和 SourceMap2 進(jìn)行合并，不幸的是很多 transformer 并不會(huì)自動(dòng)的處理這種合并，如 TypeScript，但是大部分的 bundler 都是支持自動(dòng)的 SourceMap 合并的。
如在 Rollup 里，你可以在 load 和 transform 里返回 code 的同時(shí)，返回 mapping。Rollup 會(huì)自動(dòng)將該 mapping 和 builder 變換的 mapping 進(jìn)行合并，vite 和 esbuild 也支持類似功能。如果我們需要自己處理 SourceMap 合并該如何操作，社區(qū)上已經(jīng)有庫(kù)幫我們處理這個(gè)事情。我們簡(jiǎn)單看下
import ts from 'typescript';
import { minify } from 'terser';
import babel from '@babel/core';
import fs from 'fs';
import remapping from '@ampproject/remapping';
const code = `
const add = (a,b) => {
return a+b;
}
`;
const transformed = babel.transformSync(code, {
filename: 'origin.js',
sourceMaps: true,
plugins: ['@babel/plugin-transform-arrow-functions']
});
console.log('transformed code:', transformed.code);
console.log('transformed map:', transformed.map);
const minified = await minify(
{
'transformed.js': transformed.code
},
{
sourceMap: {
includeSources: true
}
}
);
console.log('minified code:', minified.code);
console.log('minified map', minified.map);
const mergeMapping = remapping(minified.map, (file) => {
if (file === 'transformed.js') {
return transformed.map;
} else {
return null;
}
});
fs.writeFileSync('remapping.js', minified.code);
fs.writeFileSync('remapping.js.map', minified.map);
//fs.writeFileSync('remapping.js.map', JSON.stringify(mergeMapping));
我們來(lái)簡(jiǎn)單驗(yàn)證下效果
使用 mergeMapping 之前
使用 mergeMapping 之后
我們可以看出做了 mergeSourcemap 后可以成功的還原出最初的源碼
性能 matters
我們支持好了上面的 SourceMap 生成和 SourceMap 合并了，迫不及待的在業(yè)務(wù)中加以使用了，但是卻“驚喜”的發(fā)現(xiàn)整個(gè)構(gòu)建流程的速度直線下降，因?yàn)?SourceMap 操作的開(kāi)銷實(shí)際上是非常可觀的，在不需要 SourceMap 的情況下或者在對(duì)性能極其敏感的場(chǎng)景下（服務(wù)端構(gòu)建），實(shí)際是不建議默認(rèn)開(kāi)啟 SourceMap 的，事實(shí)上 SourceMap 對(duì)性能極其敏感，以至于 source-map 庫(kù)的作者們重新用 rust 實(shí)現(xiàn)了 source-map，并將其編譯到了 webassembly。
錯(cuò)誤日志上報(bào)和反解
當(dāng)我們處理好 SourceMap 的生成后，就可以進(jìn)行日志上報(bào)了
Sentry
錯(cuò)誤上報(bào)需要解決的一個(gè)問(wèn)題就是統(tǒng)一上報(bào)格式問(wèn)題，我們生產(chǎn)環(huán)境遇到的錯(cuò)誤并非直接將原始的 Error 信息上報(bào)給服務(wù)端的，而是需要先進(jìn)行格式化處理，如下面這種錯(cuò)誤
function inner() {
myUndefinedFunction();
}
function outer() {
inner();
}
setTimeout(() => {
outer();
}, 1000);
原始的錯(cuò)誤堆棧如下
Sentry Client 會(huì)將其先進(jìn)行格式化處理，Sentry 發(fā)送給后端的錯(cuò)誤堆棧格式下面這種格式化數(shù)據(jù)
問(wèn)題來(lái)了，為啥 Sentry 要經(jīng)過(guò)這樣一番格式化處理，以及格式化處理中可能會(huì)發(fā)生什么問(wèn)題呢。
V8 StackTrace API
按理來(lái)講 Error 對(duì)象作為標(biāo)準(zhǔn)里規(guī)定的 Ordinary Object ，其在不同的 JS 引擎上表現(xiàn)行為應(yīng)該一致，但是很不幸，標(biāo)準(zhǔn)里雖然規(guī)定了 Error 對(duì)象是個(gè) Ordinary Object，但也只規(guī)定了 name 和 message 兩個(gè)屬性的行為，對(duì)于最廣泛使用的 stack 屬性，并沒(méi)有加以定義，這導(dǎo)致了 JS 引擎在 stack 屬性的表現(xiàn)差別很大（目前已經(jīng)有一個(gè)標(biāo)準(zhǔn)化 stack 的 proposal），甚至有的引擎實(shí)現(xiàn)已經(jīng)突破了標(biāo)準(zhǔn)的限定，使得 Error 表現(xiàn)的更像一個(gè) Exotic Object。我們來(lái)具體看看各引擎對(duì)于 Error 對(duì)象的實(shí)現(xiàn)差異。
V8 支持了 stack 屬性，并且給 stack 屬性提供了豐富的配置，如下是一個(gè)基本的 stack 信息。
function inner() {
myUndefinedFunction();
}
function outer() {
inner();
}
function main() {
try {
outer();
} catch (err) {
console.log(err.stack);
}
}
main();
我們可以使用 https://github.com/GoogleChromeLabs/jsvu 來(lái)很方便的測(cè)試不同 JS 引擎的表現(xiàn)差異
V8 的 stacktrace默認(rèn)最多展示 10 個(gè) frame，但是該數(shù)目可以通過(guò) Error.stackLimit 進(jìn)行配置,同時(shí) V8 也支持了 async stacktrace，默認(rèn)也會(huì)展示 async|await 的錯(cuò)誤棧。
stacktrace 的捕獲不僅僅可以在出現(xiàn)異常時(shí)觸發(fā)，還可以業(yè)務(wù)主動(dòng)捕獲當(dāng)前的 stacktrace，這樣我們就可以基于此實(shí)現(xiàn)自定義 Error 對(duì)象。
Error.captureStackTrace
V8 提供了 Error.captureStackTrace 支持用戶自定義收集 stackTrace。
這個(gè) API 主要有兩種功能，一個(gè)是給自定義對(duì)象追加 stack 屬性，達(dá)到模擬 Error 的效果
function CustomError(message) {
this.message = message;
this.name = CustomError.name;
Error.captureStackTrace(this); // 給對(duì)象追加stack屬性
}
try {
throw new CustomError('msg');
} catch (e) {
console.error(e.name); // CustomError
console.error(e.message); //msg
console.error(e.stack);
/*
CustomError: msg
at new CustomError (custom_error.js:4:9)
at custom_error.js:7:9
*/
}
另一個(gè)作用就是可以隱藏部分實(shí)現(xiàn)細(xì)節(jié)，這一方面可以避免一些對(duì)用戶無(wú)用的信息泄露給用戶，而對(duì)用戶造成困擾；另一方面可能有一些內(nèi)部信息涉及一些敏感信息，需要防止泄露給用戶。比如一般用戶是不需要關(guān)心 native 的調(diào)用棧，因此就需要將 native 的調(diào)用棧進(jìn)行隱藏。下面的例子就簡(jiǎn)單的演示了如何通過(guò) captureStackTrace 來(lái)隱藏部分調(diào)用棧信息。
function CustomError(message, stripPoint) {
this.message = message;
this.name = CustomError.name;
Error.captureStackTrace(this, stripPoint);
}
function leak_secure() {
throw new CustomError('secure泄漏了');
}
function hidden_secure() {
throw new CustomError('secure沒(méi)泄露', outer_api);
}
function outer_api() {
try {
leak_secure();
} catch (err) {
console.error('stk:', err.stack);
}
try {
hidden_secure();
} catch (err) {
console.error('stk2:', err.stack);
}
}
outer_api();
Error.prepareStackTrace
另一個(gè)值得注意點(diǎn)的是，雖然 stack 名義上應(yīng)該是一個(gè) frame 的數(shù)組，但是實(shí)際上 stack 卻是個(gè)字符串（歷史包袱，兼容性問(wèn)題吧），因此 V8 同時(shí)提供了一個(gè)結(jié)構(gòu)化的 stack 信息，方便用戶根據(jù)結(jié)構(gòu)化的 stack 信息來(lái)自定義 stack 結(jié)構(gòu)。我們可以通過(guò) Error.prepareStackTrace 來(lái)獲取原始的棧幀結(jié)構(gòu)：
Error.prepareStackTrace = (error, structedStackTrace) => {
for (const frame of structedStackTrace) {
console.log('frame:', frame.getFunctionName(), frame.getLineNumber(), frame.getColumnNumber());
}
};
其中的 structedStackTrace 是個(gè)包含了 frame 信息的數(shù)組，其中包含了很多我們感興趣的信息，更詳細(xì)的信息可參考 stack-trace-api。
另外 stack 雖然是個(gè) value property ，但是實(shí)際表現(xiàn)卻是個(gè) getter property，這也是 V8 的實(shí)現(xiàn)違反 EcmaScript 規(guī)范的地方。
這里的 stack 雖然是個(gè) value，但是其表現(xiàn)其實(shí)更像是一個(gè) getter，因?yàn)槠湓L問(wèn) stack 的屬性會(huì)觸發(fā) prepareStackTrace 回調(diào)。這導(dǎo)致 error.stack 實(shí)際上是可能存在副作用的。不僅如此， stack 屬性的計(jì)算也是惰性計(jì)算的，當(dāng) error 觸發(fā)的時(shí)候并不會(huì)進(jìn)行 stack 的計(jì)算，而只有當(dāng)首次訪問(wèn) stack 的時(shí)候才會(huì)觸發(fā)計(jì)算，因?yàn)楸旧?stack 的計(jì)算實(shí)際上是有一定的性能開(kāi)銷的，實(shí)際上 chrome devtools 就因?yàn)?stackstrace 的性能問(wèn)題出過(guò)問(wèn)題（faster-stack-trace），筆者也因?yàn)?stack-trace 的性能問(wèn)題導(dǎo)致嚴(yán)重影響了編譯工具的編譯性能（https://github.com/evanw/esbuild/issues/1039）。
Stack Trace Format
前面已經(jīng)提到 V8 的 stack 是個(gè)字符串，如果需要將一個(gè)字符串解析為一個(gè)結(jié)構(gòu)化數(shù)據(jù)，勢(shì)必該字符串需要符合某個(gè)格式規(guī)范，幸運(yùn)的是 V8 的有一套格式規(guī)范，具體格式可見(jiàn) stack-trace-format。雖然 V8 引擎定義了一套格式規(guī)范，不幸的是其他引擎的 stack 格式規(guī)范與 V8 截然不同（不帶重樣的），我們來(lái)看看不同引擎的格式規(guī)范。
V8（Chrome）
SpiderMonkey（Firefox）
JavaScriptCore（Safari）
QuickJS
我們發(fā)現(xiàn)四個(gè) JS 引擎的 stack 格式各不相同，因此需要我們?cè)谏蠄?bào)錯(cuò)誤前需要將這些格式進(jìn)行分別的格式化處理，幸運(yùn)的是 Sentry Client 已經(jīng)幫我們給主流的 JS 引擎做了適配。
sentry-compute-stack-trace
不幸的是，如果你的 JS 引擎是自研的或者 stack 格式和上述的引擎都不一致，你可能需要修改 Sentry 加以支持。
這里我們還發(fā)現(xiàn)了一個(gè)比較嚴(yán)重的問(wèn)題就是 QuickJS 引擎的報(bào)錯(cuò)是沒(méi)有行列號(hào)信息的，這對(duì)于平時(shí)的開(kāi)發(fā)可能足夠了，但是如果你將你的代碼壓縮成一行，那么就會(huì)導(dǎo)致行列號(hào)信息都被丟失了，那么上報(bào)的錯(cuò)誤是根本沒(méi)法進(jìn)行反解的。更加不幸的是 QuickJS 至今仍然不支持列信息，如果你的系統(tǒng)里使用了 QuickJS，可能需要修改 QuickJS 自行添加列號(hào)支持。
eval is eval
如果你的代碼是在 eval 里執(zhí)行，那么將會(huì)碰到另一個(gè)問(wèn)題，有的 JS 引擎針對(duì) eval 的代碼并不會(huì)包含錯(cuò)誤的行列號(hào)信息。
const code = `function inner() {
myUndefinedFunction();
}
function outer() {
inner();
}
function main() {
try {
outer();
} catch (err) {
console.log(err.stack);
}
}
function foo() {
bar();
}
function bar() {
main();
}
foo();
eval(code);
比如我們看一下不同引擎的結(jié)果
V8 雖然包含了行列號(hào)信息，但是堆棧里含有了兩個(gè)行列號(hào)信息，可能導(dǎo)致 sentry-client 識(shí)別出錯(cuò)
JavascriptCore 則徹底沒(méi)有行列號(hào)信息
SpiderMonkey 雖然能夠顯示，但與非 eval 版本格式完全不同，很難兼容
其實(shí)為了解決 eval 的錯(cuò)誤堆棧的行列號(hào)問(wèn)題，我們可以借助 sourceURL 進(jìn)行還原，我們來(lái)看一看結(jié)果
const code = `function inner() {
myUndefinedFunction();
}
function outer() {
inner();
}
function main() {
try {
outer();
} catch (err) {
console.log(err.stack);
}
}
function foo() {
bar();
}
function bar() {
main();
}
foo()
//# sourceURL=my-foo.js
`; // 這里通過(guò)sourceURL支持還原
eval(code);
V8：成功還原
JavaScriptCore：不支持
SpiderMonkey：成功還原
anonymous function is bad
解決了 eval 的問(wèn)題后，似乎可以高枕無(wú)憂了，但是實(shí)際開(kāi)發(fā)中仍然碰到了一些匪夷所思的問(wèn)題，線上反解仍然失敗，后來(lái)定位發(fā)現(xiàn) JavaScriptCore 在生成異常的時(shí)候，其行列號(hào)可能計(jì)算錯(cuò)誤，以及給 QuickJS 引擎添加的行列號(hào)功能也存在不少 bug。那么在行列號(hào)不靠譜的情況下如何查問(wèn)題。那就只能借助于 function name 去全局搜索了，不幸的是我們的業(yè)務(wù)中和 SDK 中存在大量的匿名函數(shù)，這無(wú)異于雪上加霜。
對(duì) YDKJS 的觀點(diǎn)深感贊同，不幸的是 JavaScript 里將 anonymous function 和 lexical this 兩個(gè) feature 糅合在一起了，你除了通過(guò)變量聲明的方式，沒(méi)有其他更簡(jiǎn)潔的方式來(lái)給一個(gè) arrow function 進(jìn)行命名
const xxx = () => {} // xxx.name is xxx
call('login', () => {
this.crash()
}) // 如果這里crash了，很不幸調(diào)用棧里拿不到函數(shù)名了
const cb = () => {this.crash()}
call('login', cb) // 太繞了。。。。
call('login', function loginCb(){
this.crash()
}.bind(this)) // 還是很繞
call('login', loginCb() => { // 這樣就最好了，可惜不支持，we need a proposal
this.crash();
})
如果 arrow function 也能便捷的命名就好了。
SourceMap 的局限
代碼反解只是 SourceMap 的一個(gè)功能，其實(shí)還扮演著源碼調(diào)試等功能，但是 SourceMap 在源碼調(diào)試上卻面臨著更大的問(wèn)題和挑戰(zhàn)，比如難以應(yīng)對(duì)其他高級(jí)語(yǔ)言的轉(zhuǎn)換問(wèn)題，例如 C++ 編譯到 asm.js 或者 C++編譯為 wasm，如何處理 wasm 或者 asm.js 的源碼調(diào)試和代碼反解，是另一個(gè)比較復(fù)雜的話題了。
參考文獻(xiàn)
https://github.com/Rich-Harris/vlq/tree/master/sourcemaps https://www.ruanyifeng.com/blog/2013/01/javascript_source_map.html https://tc39.es/ecma262/#sec-error-objects getOwnPropertyDescriptor side effects https://bugs.chromium.org/p/v8/issues/detail?id=5834 https://hacks.mozilla.org/2018/01/oxidizing-source-maps-with-rust-and-webassembly/