Ender 源码地图揭秘：vlq.js 中 VLQ 可变长度编码的实现原理全解析

• 开发工具

在 Ender——这个面向浏览器的 JavaScript 开源包管理器（the no-library library）中，压缩产物能精确回溯到每一行源码，靠的正是一份 Source Map（源码地图）。而这份地图的“压缩语言”，就是 lib/vlq.js 里仅 70 多行代码实现的VLQ 可变长度编码（Variable Length Quantity）。本文带你读懂 Ender 源码中这套编码的每一个关键函数与位运算细节。

先搞懂：为什么 Source Map 要用 VLQ 编码

浏览器调试时，压缩后的代码往往被压成寥寥几行。Source Map 通过mappings字段记录“压缩代码 → 源码文件/行/列”的对应关系。但这份映射如果直接存数字，体积会非常大。

VLQ 编码正是为此而生，它有两个核心设计：

• 可变长度：小数字只用 1 个字符表示，大数字才用多个字符，天然压缩；
• 差分编码 + 支持负数：相邻映射点只存“差值”而非绝对值，差值有正有负，VLQ 用zigzag（之字形）变换让负数也能用无符号位安全表示。

理解下面三个概念，源码基本就能看懂了：

读懂四个核心常量与函数

打开 lib/vlq.js，文件开头的定义是理解一切的钥匙：

var VLQ_BITS = 5 , VLQ_BASE = 1 << VLQ_BITS // 32，即续传位（第 6 bit） , VLQ_MASK = (1 << VLQ_BITS) - 1 // 31，取出 5 bit 数据的掩码 , itob64 = 'ABC...xyz0123456789+/'.split('') , b64toi = {} // 反向查表：字符 → 数字 , toVLQ = function (val) { return val < 0 ? (-val << 1) | 1 : (val << 1) } , fromVLQ = function (vlq) { return vlq & 1 ? -(vlq >>> 1) : (vlq >>> 1) }

逐条拆解：

• VLQ_BITS = 5：每个“数字块”（digit）只有 5 bit，最多表示 0~31；
• VLQ_BASE = 32：也就是二进制100000，第 6 位被留作续传位——为 1 表示后面还有数字块；
• VLQ_MASK = 31：二进制011111，用它做按位与就能“截”出 5 bit 有效数据；
• itob64/b64toi：两个互为反向的查表。itob64[n]把数字换成字符，b64toi[c]把字符还原成数字（由文件末尾的forEach一次性初始化）；
• toVLQ/fromVLQ：zigzag 编码与解码。以-3为例：(-(-3) << 1) | 1 = 7，最低位1被借来表示“它是负数”，解码时fromVLQ(7)就还原回-3。

编码流程逐行解读：encode 函数

encode负责把任意整数（含负数）变成 Base64VLQ 字符串，核心逻辑在 lib/vlq.js：

, encode = function (val) { var result = '' , vlq = toVLQ(val) // 第 1 步：zigzag，负数变正数 , digit do { digit = vlq & VLQ_MASK // 第 2 步：取出最低 5 bit vlq >>>= VLQ_BITS // 第 3 步：右移 5 bit，丢弃已处理部分 if (vlq) digit |= VLQ_BASE // 第 4 步：还有剩余？打上续传位 result += itob64[digit] // 第 5 步：查表转字符，拼进结果 } while (vlq > 0) return result }

四个关键动作循环往复，直到vlq被移空：

1. 切块：vlq & VLQ_MASK每次截出最低 5 bit；
2. 移位：vlq >>>= 5（无符号右移）把已处理的部分丢掉；
3. 打标记：只要还有剩余，就digit |= 32，告诉解码者“我还没说完”；
4. 查表输出：把 6 bit 的数字（5 bit 数据 + 1 bit 标记）通过itob64换成一个 Base64 字符。

解码流程逐行解读：decode 函数与一个易错点

解码是编码的镜像操作，位于 lib/vlq.js：

, decode = function (vlqstr) { var result = 0 , digit , continuation , i for (i = 0, continuation = 1; continuation && i < vlqstr.length; i++) { digit = b64toi[vlqstr[i]] // 字符还原为数字 continuation = digit & VLQ_BASE // 读取续传位 digit &= VLQ_MASK // 去掉续传位，只留 5 bit 数据 result += digit << (VLQ_BITS * i) // 第 i 块放到第 i 个位置 } if (continuation && i == vlqstr.length) return NaN return { value: fromVLQ(result), rest: vlqstr.slice(i) } }

两个值得注意的细节：

• result += digit << (VLQ_BITS * i)：第i个字符块左移5*i位再累加，正好还原出完整整数；
• 返回结构是{ value, rest }：mappings里多段编码是连在一起的，rest返回“没读完的剩余字符串”，方便调用方接着解下一段；
• NaN陷阱：如果字符串在读完时续传位仍为 1（说明编码被截断、不完整），函数返回NaN而不是抛错——这是静默失败设计，读源码时容易被忽略。

最后别忘了fromVLQ：把累加得到的无符号数还原回可能有负号的原始差值。

动手验算：encode 与 decode 的真实结果

拿真实数字跑一遍，印象会深刻得多：

以39为例完整走一遍：

• 第 1 块：78 & 31 = 2，移位后vlq = 2非零，打续传位 →2 | 32 = 34→ 查表itob64[34]得字符C；
• 第 2 块：2 & 31 = 2，移位后vlq = 0，不打续传位 →itob64[2]得字符g；
• 结果：39 → "Cg"。反向解码时，C的低 5 位01110放个位，g的低 5 位00010左移 5 位相加，得到78，fromVLQ(78)即78 >>> 1 = 39，完美还原。

Ender 在哪里用上了 VLQ 编码：源码地图实战

VLQ 不是孤立模块，它在 Ender 的构建流程里承担核心角色。在 lib/assemble.js 的generateMappings函数中，每一行源码都被转成 4 段 VLQ 编码：

return ( vlq.encode(indent || 0) + // 压缩后的列偏移（缩进调整） vlq.encode(sourceIndexDelta) + // 源文件索引差值 vlq.encode(sourceLineDelta) + // 源码行号差值 vlq.encode(0) + // 源码列号（恒为 0） (ending ? ';' : '') // 行尾分隔符 )

这里就能看到差分编码的威力：sourceIndexDelta和sourceLineDelta存的不是绝对行号，而是与上一行的差值——差值大多是小整数，经 VLQ 压缩后通常只需 1 个字符。最终这些字符串会被build.map.mustache模板拼装进mappings字段，与构建产物一起输出。

想顺藤摸瓜，可以按这条线索继续读：

• 编码实现：lib/vlq.js
• 使用方（生成映射）：lib/assemble.js
• 构建入口（编译打包）：lib/commands/compile.js
• 项目说明：README.md

小结

Ender 的 lib/vlq.js 用 70 行代码完整实现了 Source Map 标准中 Base64VLQ 的全部规则：

1. zigzag 变换（toVLQ/fromVLQ）解决负数问题；
2. 5 bit 分块 + 续传位（encode/decode循环）实现“小数省字符、大数多字符”的可变长度压缩；
3. Base64 双向查表（itob64/b64toi）把位数据翻译成可打印字符；
4. { value, rest }返回值 + NaN 边界处理让解码器能流式地一段段解析mappings字符串。

读懂它，你就同时理解了 Ender 源码地图的“语言”和 Source Map v3 规范中最精巧的部分。

• 开发工具