零 npm 运行时依赖手写 ITU-T T.81 基线 JPEG,jpeg-js 与 pngjs 只出现在 tests/ 当 oracle。解码侧:段解析器覆盖 SOI/APP0/DQT/SOF0/DHT/SOS/COM/DRI,段长全程边界校验、段后游离字节即抛;MSB-first 位读取器处理 0xFF00 转义,遇真标记关闭位源、余位按 T.81 F.2.2.5 以 1 填充;Huffman 用 8 位前缀快速表全展开,9..16 位落慢路径(mincode/maxcode/valptr),建表时码空间超额即抛。IDCT 三实现互当裁判:朴素 O(N⁴) 双精度参考、行列分离 O(N³) 主力、AAN 整数化 12 位定点(round(4096·cos),全零 AC 快速路径)当生产默认,全零/DC-only/64 个单系数位置/500 随机块/100 极端块两两差分 ≤1 LSB。YCbCr BT.601 全范围,4:4:4/4:2:0/4:2:2 上采样最近邻 floor(x·h/maxH)(左上对齐盒式复制),28 种尺寸矩阵 × 2 采样模式全过;restart marker 编码端 DRI+RSTn+DC 预测重置,解码端宽容不校验序号(libjpeg 同款),熵数据无声耗尽一律抛错。编码侧 FDCT 行列分离、量化 round(F/q)、Annex K 表 × IJG 质量映射(q<50 → 5000/q,否则 200−2q)、Z 字形表脚本生成防手误、DC 差分 + AC 游程/尺寸联合编码、0xFF 字节填充,encode 出的流必须被 jpeg-js 与自家解码器双双解开。差分验收:73 张语料全部 100% 像素逐字节相等(要求 ≥99.9%)、编码闭环 100 图 |ΔPSNR| 最大 0.0000 dB、坏流 2000 条全抛错无死循环、125/125 测试 + tsc strict 零错误。抓虫实录八条:双重 Z 字形映射(熵解码写自然序、IDCT 又映射一次,DC-only 图完美而 AC 图全糊——往返自洽测试掩盖方向性错误)、AAN stage-2 sin/cos 配对写反(输出每半段镜像,靠 jpeg-js 原版逐字对跑定位)、DQT 的 Pq/Tq 误写两字节(后续表全错位)、ZRL 逐 16 个发射让纯色块位流膨胀 10 倍(30→4 字节)、loadByte 多跳一字节(restart 语料数据正确率恰为 1/6,分数本身就是诊断线索)、扫描区间不含结束标记、扫描尾标记从未被主循环消费(改回主循环消费反而白赚扫描间 DHT 更新)、语料有 RSTn 无 DRI 双解码器同时拒收。性能与 jpeg-js 同档(±8%),编码输出反而小 13-14%;Web UI 单文件 27.7KB 已部署 https://jpeg-lab.pages.dev。已知限制:SOF2 进度式、算术编码、12 位、CMYK、分层模式全部抛错。
往返测试第一次全绿的时候,我以为编码器已经成了。自家编码器压出的图喂回自家解码器,逐像素相等。
然后我把同一张图交给 jpeg-js 当裁判:整幅糊成马赛克。唯独那几张 DC-only 的测试图,纹丝不动地全绿。这个组合本身就是诊断书——不是某一步算错了,而是两步之间对"系数在数组里的第几个位置"各执一词,而往返测试的两半恰好共享同一份错误约定。这是差分验收给我上的第一课,发生在编码与解码第一次同时能跑的当晚。

图背后是一套从零手写的基线 JPEG 编解码器:段解析、Huffman、三套 IDCT、YCbCr、色度上下采样,加上 FDCT 与熵编码的闭环。运行时零 npm 依赖,jpeg-js 只出现在 tests/ 里当 oracle。这篇记它的骨架、差分验收怎么设计,以及八条抓虫实录——每一条都是两种"看着都对"的口径在打架。
为什么是 JPEG
1992 年冻结的 ITU-T T.81,到今天没改过一行,而它是全世界每天被解码次数最多的格式之一:相机存的是它,浏览器打开的是它,聊天窗口转发的还是它。三十年无人修订意味着实现写完就是终点——没有版本漂移,没有破坏性更新。这是"零维护项目群"的选题标准,JPEG 是这个群里的又一名成员。
任务书把验收锁死在"差分"两个字上,原话管它叫"本项目的灵魂":解码对拍 ≥50 张图,与 jpeg-js 逐像素比较,≥99.9% 像素相等、其余通道差 ≤1;编码闭环 100 张图,encode 出的流必须被 jpeg-js 和自家 decodeJpeg 双双解开,两者与原图的 PSNR 一致到 ±0.1 dB;坏流 2000 条全部抛错,不许死循环越界。裁判不上场,只看比赛。
段与流:MCU 的几何学
JPEG 文件由标记分段:SOI、APP0(JFIF)、DQT、SOF0、DHT、DRI、SOS、COM……解析器做两件事:把骨架拆出来,并且不许太宽容。
- 段长度字段全程边界校验,段结束必须紧跟 0xFF,游离的数据字节一律按流损坏抛错;
- 非法标记码、分层模式(DHP/EXP)、JPG 保留段、算术编码(SOF9)、12 位精度、四分量 CMYK、SOF2 进度式——全部抛出中文明确的错误;
- 宽容是对格式的不忠。
真正的几何学在 SOS 之后。基线扫描把图像切成 MCU(最小编码单元):4:4:4 时一个 MCU 就是 8×8 一块;4:2:0 时是 16×16,装 4 个亮度块加 Cb/Cr 各一块。图像尺寸不是 MCU 整数倍时,编码侧把边缘块重复采样填满、解码侧把多出来的部分丢掉——两侧约定对不齐,差分就是一整条噪点带。28 种尺寸矩阵(1×1、非 8 倍数、MCU 边界两侧)× 2 种采样模式,全部进了差分语料。
熵流自带两套小规矩。0xFF 是标记前导,熵数据里出现它必须后跟 0x00 占位,编码侧填充、解码侧剥离;真标记一到,位源关闭,余位按 T.81 F.2.2.5 以 1 填充——标记像一堵墙,墙外的位不算数。
Huffman 解码不走树。码长序列建表时全展开成 8 位前缀快速表,命中数据等于一次掩码加一次查表;超过 8 位的码落进 mincode/maxcode/valptr 的慢路径逐位判定。建表之前先过码空间校验,超额即抛——一张非法表撑不起任何合法输出。
restart marker 是基线 JPEG 少有的容错设计。编码端按 DRI 约定每 interval 个 MCU 字节对齐插入 RSTn 并重置 DC 预测,restartInterval 是任务书签名之上的附加参数,专门为生产 restart 语料服务;解码端读到的 RSTn 序号不校验——libjpeg 同款宽容——但熵数据无声耗尽、没有标记撑腰就混过 MCU 计数的截断流,一律抛错。想靠 1 填充蒙混过关,没门。
IDCT:三套实现互当裁判
IDCT 是解码端唯一的重数学,任务书要求三种实现都会写,而且互相差分:
- naive,O(N⁴):按定义写四重和,双精度浮点。慢得心安理得,职责是当参考答案;
- rowcol,O(N³):行列分离,先每行做一维 DCT-III 再每列做一遍。主力实现;
- aan,整数化:12 位定点常数 round(4096·cos),全零 AC 快速路径,输出
128+((p+8)>>4)饱和。优化实现,也是生产默认,与 libjpeg jidctint 同源。
差分测试铺五类语料:全零块、DC-only 块、64 个单系数位置各来一个(顺带验证 Z 字形表的每个格子)、500 个随机量化块、100 个极端幅值块,两两比较,全部 ≤1 LSB。decodeJpeg 的 opts.idct 参数就是为此开的口子,教学演示也靠它。
三套各写一遍的真正价值不在性能,在于"参考答案"这个概念有了实体——后面 AAN 那条虫,就是靠朴素版当第三方法庭定罪的。
已知边界如实入档:整数化实现工作在 ±2048 以内的反量化系数上(现实 JPEG 的 DC 真值上限 2040,够用),超出会累积截断误差,±8191 实测 2 LSB——libjpeg jidctint 同款限制,差分承诺范围之外。
色度与上采样的坑
JPEG 不存 RGB。编码前做 BT.601 全范围的 YCbCr 变换,色度按 4:4:4/4:2:2/4:2:0 抽样——人眼对亮度敏感、对色度迟钝,省下的比特全从这里来。解码端再倒回去:反量化、IDCT 出分量平面,色度平面用最近邻 floor(x·h/maxH) 上采样回全尺寸(左上对齐的盒式复制,libjpeg 默认口径),最后 YCbCr→RGB,clamp(Y+1.402(Cr−128)) 这一族的公式收尾。
这一段的坑全在"约定"上。上采样用哪个公式、色度居中对齐还是左上对齐、clamp 完赋值给 Uint8Array 是四舍五入还是截断——T.81 一概没规定,每种选择都合法,但只有一种和 oracle 一致。
我们的答案是对齐主流实现:浮点乘后 clamp,经 Uint8Array 赋值自然截断;上采样盒式复制。任务书的停止规则写得很硬:差分不收敛时如实记录并停止,不许改 oracle 口径凑绿——口径不是讨价还价的对象,是差分能否成立的前提。
编码闭环:FDCT、量化与熵编码
编码侧是把解码管线倒着走一遍,但每一步都要自己做主。RGBA 进来,先做 MCU 对齐的边缘填充,RGB→YCbCr,4:2:0 时盒式下采样(API 可选 4:4:4)。然后逐块 FDCT(行列分离)、量化 round(F/q):量化表来自 Annex K 的标准亮度/色度表乘 IJG 质量映射——q<50 时 scale=5000/q,否则 200−2q,表值 clamp 到 [1,255]。
JPEG 的"有损"就发生在这里:高频系数被大步长除过,小值直接归零。
熵编码是纯手艺活:系数按 Z 字形扫描(表由脚本生成防手误——后来证明表没出错,虫出在别处);DC 系数与上一块差分编码;AC 系数按"零游程 + 非零幅值尺寸"联合编码,尾零一个 EOB 收尾;每字节 0xFF 后填 0x00;最后组装 SOI/APP0/DQT/SOF0/[DRI]/DHT/SOS/EOI。四张标准 Huffman 表取自 Annex K.3,兼容性最优。
验收是双向闭环:encode 出的流,jpeg-js 要能解,自家 decodeJpeg 也要能解,两者与原图的 PSNR 一致到 ±0.1 dB。100 张语料(噪声/纯色/渐变/照片仿真/文字仿真/棋盘 × 20 种尺寸)× q85 全量跑,q10/50/95 抽样——实测 |ΔPSNR| 最大 0.0000 dB。两个解码器看同一条流,看见的东西一模一样。
差分验收与抓虫实录
验收数据先记账。解码差分 73 张,四种来源各司其职——第三方编码器产的、oracle 产的、自家编码器产的、官方测试图,把"谁能编码"这个变量铺满:
| 来源 | 张数 | 覆盖 |
|---|---|---|
| libjpeg-turbo 官方测试图 | 2 | 独立编码器、4:2:0 |
| Windows GDI+ 生成 | 18 | 渐变/文字/彩条/棋盘/噪声 × q25-95,含 257×129 奇尺寸 |
| jpeg-js 编码器生成 | 24 | 420、10 种尺寸、q10/50/85/95 |
| 自家编码器生成 | 29 | 444/422/440/420/灰度 × 10 尺寸,restart DRI∈13 × 2 尺寸 |
要求是 ≥99.9% 像素相等、其余通道差 ≤1,实测全部 100% 逐字节相等,maxDiff=0。
坏流 2000 条:800 纯随机(半数伪装 FFD8 头)+ 600 真实 JPEG 随机位置截断 + 600 字节替换/比特翻转/头部攻击 + 14 类结构化坏流(长度越界、码空间超额、采样非法……),全部抛错,无死循环无越界。变异类的抛错率与 oracle 的宽容度差异为 0——我们拒它也拒,不添一分好心。不死循环是结构保证的:MCU 计数由帧尺寸决定、块索引越界即抛、DC 预测溢出即抛,每步严格消费输入,坏流想绕圈没有物理学依据。
抓虫八条,最值钱的三条展开。
第一条就是开篇的双重 Z 字形。 熵解码把 AC 系数写进自然序位置 coef[ZZ_TO_NATURAL[k]],IDCT 又按"输入是 zz 序"做了一次映射——系数被映射两次。DC-only 图恰好免疫(DC 不走 Z 字形),有任何 AC 系数就全糊。修复是约定统一:系数块一律按 zz 序存储,映射只在 IDCT 内做一次。
它教的东西超出这个 bug 本身:往返自洽测试会掩盖方向性错误——"我们编码→我们解码"的两半共享同一份错误约定时,全绿只是两个错误在互相作证。开篇那一幕的正式名字,叫"自洽不等于正确"。
第二条:AAN stage-2 的 sin/cos 配对写反。 jpeg-js 的顺序赋值语义里,t = sin·v4 + cos·v7 这个中间量最终赋给 v7,cos 侧才赋给 v4——转写时我把 b4/b7(连同 b5/b6)交换了,输出呈"每半段镜像"图案,肉眼几乎看不出错,只在差分图上显形。
定位靠笨办法:把 jpeg-js 原版算法逐字抄一份、同输入对跑,逐级比对中间量,第一处分叉就是案发现场。转写带隐式赋值顺序的算法,最后一行赋给谁,要盯死。
第三条:restart 语料的正确率停在了 1/6。 带重启标记的差分语料,数据正确率恰好六分之一——分数本身就是诊断线索,说明损坏是周期性的,不是全程随机。位级追下去:loadByte 的标记分支写了 pos += 2,可 0xFF 已经被 pos++ 消耗过一次,标记码只需再跳 1 字节。多跳的这一字节让第一个 restart 间隔之后的所有数据错位。
其余五条从简:
- DQT 段的 Pq/Tq 被写成两字节,段内多出一个 0x00,后续表全部错位(Pq 读成了 1);
- ZRL 发射时机不对,63 个尾零被逐 16 个发 ZRL,纯色块位流膨胀 10 倍——ZRL 只该在"零游程后还有非零系数"时发射,纯尾零一个 EOB 就够,修复后纯色 8×8 位流 30→4 字节;
- 扫描区间不含结束标记,正常流的边界 lookahead 撞到尽头被误判"数据耗尽",dataEnd 纳入标记两字节解决;
- 扫描尾标记从未被主循环消费(
pos = q+2直接跳过),EOI 校验形同虚设,改回主循环消费反而白赚了"扫描间 DHT 更新"能力; - 最有趣的一条:语料生成器产出一份有 RSTn 却没有 DRI 段的流,自家解码器和 jpeg-js 同时拒收——"oracle 预筛 + 双解码器对照"一次抓住了编码与解码两侧的问题。
数字
总账:125/125 测试全绿,tsc --noEmit 零错误,差分/闭环/模糊/边界/IDCT 全部在内。质量曲线(100 图均值,420,自家编码→自家解码):
| quality | 平均大小 | 平均 PSNR | 最小 PSNR(全语料) |
|---|---|---|---|
| 10 | 798 B | 25.94 dB | 11.86 dB |
| 50 | 1124 B | 36.06 dB | 12.12 dB |
| 85 | 1590 B | 41.34 dB | 13.50 dB |
| 95 | 2250 B | 43.66 dB | 13.88 dB |
最小值被 1×1 噪声图拉低。分场景看(q85 420):纯色 47.2 / 文字 33.6 / 照片仿真 21.7 / 渐变 21.4 / 棋盘 15.4 / 噪声 13.5 dB——噪声与棋盘是 DCT 的最坏情况,低 PSNR 是物理现象而非实现缺陷。测试阈值按场景实测定标(取场景最小值下方 0.5 dB)固化,不做拍脑袋的全局线。
性能与 jpeg-js 0.4.4 对拍(Node 24 / Windows,照片型内容 q85):
| 图像 | 解码 jpeg-lab / jpeg-js(MP/s) | 编码 jpeg-lab / jpeg-js(MP/s) |
|---|---|---|
| 256×256 | 12.2 / 14.2 | 8.6 / 4.9 |
| 512×384 | 15.2 / 14.0 | 10.1 / 9.1 |
| 1024×768 | 13.4 / 14.3 | 10.7 / 11.6 |
解码与 oracle 同档(±8%),编码互有胜负:小图更快,大图略慢。压缩率反而更好——同内容同质量下输出文件是 jpeg-js 的 0.86-0.87:jpeg-js 的 AAN 前向缩放有舍入损失,我们用精确 FDCT 加 round。
封存
已知限制如实入档:
- SOF2 进度式不支持,抛错,错误信息直接点名 progressive(任务书明确要求);
- 算术编码(SOF9-15 的 DAC 路径)不做;12 位精度不做;CMYK 四分量与分层模式(DHP/EXP)不做;
- EXIF 缩略图树不解析,按 APPn 跳过;
- 整数 IDCT 在反量化系数超出 ±2048 的病态流上误差超 1 LSB;
- 色彩转换用截断而非四舍五入——单论绝对正确性后者更优,但裁判是 oracle,差分不收敛时不许改它的口径,这是停止规则的原话。
工具已上线:https://jpeg-lab.pages.dev ——拖图进去,质量与采样切换,编码前后对比加文件大小曲线,全部在浏览器本地完成;内核就是这套零依赖实现,esbuild 单文件 27.7KB。想复核:npm install && npm test,125 项测试把差分、闭环、模糊、边界一次跑完。
回头看,"零维护项目群"这一站比 DEFLATE 多了一层难度:位流的难在纪律,JPEG 的难在它于规范未定义处留了一大片自由地——每种口径都合法,只有一种能和主流实现逐字节相认。三套 IDCT 互当裁判、73 张差分语料、2000 条坏流,把这片自由地压缩成一句话:与主流实现同口径。写完即封存。
同一批的下一站是 mini-Git。前两站:《一条三十年没人改的位流:从零手写 DEFLATE/gzip 编解码器》、《让 4.19MHz 的掌机笑起来:Game Boy 模拟器三部曲》。