Understanding Source Maps: How to Debug Minified JavaScript

Preface

When code is compiled and bundled, multiple source files are merged and minified, resulting in output that differs greatly from the original source, making debugging difficult.

Source maps store the mapping between transformed code and original source positions, enabling debugging of minified code.

What is a SourceMap?

A SourceMap is a JSON file that maps the generated code back to the original source files, containing version, file, sources, sourcesContent, names, mappings, sourceRoot, and other fields.

Generated .js.map files are referenced in the bundled file via a comment like //# sourceMappingURL=main.js.map.

Generating SourceMaps

Many front‑end tools such as webpack, uglifyjs, and gulp can generate source maps; see external tutorials for details.

SourceMap Properties

version – the SourceMap spec version.

sources – array of original source file URLs.

names – array of identifiers (variables, property names) used in the original code.

sourceRoot – root path for source files.

sourcesContent – original source file contents.

mappings – base64 VLQ string that records the mapping between generated and original positions.

file – name of the generated file associated with this map.

SourceMap Versions

Version 1 (2009) originated from Google Closure Compiler. Version 2 (2010) introduced base64 encoding. Version 3 (2011) optimized the algorithm and reduced map size, and is the current standard.

SourceMap Mechanism

The mappings field is a long string divided by semicolons (line separators) and commas (segment separators). Each segment contains up to five VLQ‑encoded numbers representing column, source index, original line, original column, and name index.

VLQ encodes numbers using a continuation bit and a sign bit, allowing compact representation of both positive and negative values. The encoded numbers are then converted to base64 characters.

Example

Given a simple file const value = 123; console.log(value);, after bundling we get:

console.log(123);
//# sourceMappingURL=bundle.js.map

A corresponding source map might contain:

{ "sources": ["a.js"], "names": ["console","log"], "mappings": "AACAA,QAAQC,IADM" }

Summary

Source maps link transformed code to original sources.

Enable debugging via the //# sourceMappingURL=... comment.

Applicable to JavaScript and CSS files.

Core encoding uses base64 VLQ.

References:

https://juejin.cn/post/7023537118454480904

https://juejin.cn/post/6963076475020902436

https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit#heading=h.1ce2c87bpj24

https://www.ruanyifeng.com/blog/2013/01/javascript_source_map.html

https://www.html5rocks.com/en/tutorials/developertools/sourcemaps/

http://www.qiutianaimeili.com/html/page/2019/05/89jrubx1soc.html