OG图像生成器渲染空白卡片：一个&符号引发的静默故障

一个字符导致的隐形故障

有人构建了一个社交卡片生成器：输入标题、描述和可选头部图片，输出一张1200x630的PNG图片。功能简单直接。上线后平稳运行一周，然后收到了一条bug报告——所有标题中包含「&」符号的卡片，返回的都是纯色背景，上面没有任何文字。

最诡异的地方在于：没有异常抛出，没有错误日志，HTTP状态码始终是200。从接口层面看，一切正常。但生成的PNG图片是空白的。

故障根因：文本测量路径的实体转义缺失

问题的核心出在文本测量环节。开发者使用PIL（Python Imaging Library）的默认字体进行布局计算——通过测量字符串宽度来决定换行策略和字号大小。

ImageFont.load_default()本身不支持字体回退机制，但这还不是关键。真正的问题在于：标题字符串被直接传入了绘图上下文，而这个上下文从早期迭代中继承了对HTML实体的假设处理逻辑。像Q&A Session这样的标题被当作实体引用（&）解析，最终静默地产生了一个空字符串交给绘制调用。

没有异常，没有日志行，只有一张空白卡片。

HTML实体引用是指用&开头、以分号结尾的特殊序列，用于在HTML/XML中表示保留字符或不可直接输入的字符，例如&代表&、<代表<。当一段文本被错误地按实体规则解析时，解析器会寻找&...;模式并将其替换为对应字符；如果找不到合法的实体名，某些宽松的解析器会直接吞掉该片段，导致输出内容被静默截断。本案例中Q&A Session里的&A被当作实体起始，最终坍缩为空字符串。

**字体回退（font fallback）**指当主字体缺少某字符的字形时，渲染引擎自动切换到其他包含该字形的字体。PIL的ImageFont.load_default()只提供一套位图字体，当字符串包含它不支持的字符时，通常会回退为空白或占位符，而不会报错。这解释了为什么即使字符串本身没有异常，测量出的宽度也可能异常偏小或为零。

修复方案：无聊但正确

修复方式简单且正确：在测量之前进行转义，永远不要假设输入已经过清理。

具体做法是在任何布局计算之前调用html.escape(title)，然后绘制转义后的字符串。此外还加了一道防线——如果测量出的文本宽度坍缩为零，则拒绝渲染。宁可大声报错，也不要交付一张空白图片。

这个修复揭示了一个更普适的原则：在文本处理和图像渲染的交界处，输入清理的缺失会导致最难以察觉的bug。

html.escape()是Python标准库html模块提供的函数，默认把&、<、>替换为&、<、>，并可选转义引号。它的语义是为输出到HTML上下文中做安全准备，而非“清洗数据”。在本案例中，由于下游的绘图上下文错误地期望HTML实体，先调用html.escape()恰好让&变成了&，从而避开了被当作残缺实体吞掉的行为。这是一种在错误抽象层之间对齐预期的临时手段——更根本的修复应当是移除绘图上下文对HTML实体的隐式假设，但这在遗留代码中往往代价较高。

核心教训：图像生成API的静默失败模式

这次经历反复验证了一个容易被忽视的事实：图像生成API的失败方式与文本API截然不同。

一个空白的PNG是完全合法的响应。从HTTP协议的角度看，服务器成功处理了请求并返回了200状态码。内容类型正确，文件格式正确，响应体长度也正常。但图片里面什么都没有。

这意味着监控策略必须升级：不能只检查HTTP状态码，而要验证像素内容本身。对于任何图像生成服务，这是避免用户看到空白结果的第一道也是最重要的一道防线。

开发者将这个工具打包发布在 x402.freeq.one/tools/og_image_generator.html，如果你也在构建类似的社交卡片生成功能，这个坑值得提前避开。

空白的PNG在字节层面是一张合法图像：它包含正确的PNG签名、IHDR块和IDAT数据，只是像素全部为单一颜色。因此任何基于响应大小、Content-Type或magic number的检查都无法发现问题。要检测这类故障，监控程序需要把响应体解码为像素矩阵，然后统计颜色分布、非背景像素比例或文本区域的平均亮度。常用的轻量做法包括：计算图像的颜色方差、检测边缘数量、或对渲染结果做感知哈希并与基准图对比。这些指标一旦低于阈值即触发告警，能在用户发现空白卡片之前就暴露问题。