FFmpeg WebP 管道输出兼容排查

预览优化先保留原文件#

原来的列表卡片直接加载图片原件，视频卡片也会请求成片文件。懒加载可以推迟请求，却不会缩小文件，也不会减少图片解码所需的工作。

这次将列表改为静态预览：图片等比缩到最长边 768 像素，视频生成一张封面；打开详情、下载以及模型输入继续使用原件。预览按需生成，保存在独立的衍生缓存中，上传和视频生产不必等待它完成。

素材是私有的，所以缩略图也走鉴权接口。缓存命中不能代替权限判断，带 If-None-Match 的请求也要先鉴权，再决定是否返回 304。浏览器收到的是 Cache-Control: private, no-cache、ETag 和 Vary: Cookie。转换期间还可能撤权或修改文件，因此冷生成结束后会再次核对权限和源版本。

这些边界保留了下来，但最初的编码验证漏了一个环境差异：开发机使用 FFmpeg 9，生产镜像使用 5.1.9。

有输出，不代表文件完整#

排查时先看实际输出字节，而不是继续调整前端。一个失败样本已经生成了 46,164 字节的数据，前四字节也是 RIFF，但偏移 4 的长度字段为零。应用的格式校验因此拒绝将它作为成功预览返回。

WebP 使用 RIFF 容器。文件头的长度字段是小端无符号整数，表示从偏移 8 开始的文件大小；对于这里生成的完整 WebP，应等于总字节数减 8。WebP 容器规范给出了字段位置与含义。

下面是只读检查文件头的精简示例，并非完整 WebP 校验器；它不会验证所有 chunk、尺寸或图像能否解码：

1
import { readFileSync } from 'node:fs';
2

3
const bytes = readFileSync('preview.webp');
4
if (bytes.length < 12) throw new Error('文件头不完整');
5
if (bytes.toString('ascii', 0, 4) !== 'RIFF' ||
6
    bytes.toString('ascii', 8, 12) !== 'WEBP') {
7
  throw new Error('不是预期的 WebP 容器');
8
}
9

10
const declared = bytes.readUInt32LE(4);
11
console.log({ actual: bytes.length, declared });
12
if (declared !== bytes.length - 8) {
13
  throw new Error('RIFF 长度与实际文件不一致');
14
}

这一步把问题从“页面显示不出来”缩小到了输出格式。退出码、文件扩展名和非空 stdout 都不能替代内容验证。

限定到版本、参数和单帧输出#

当时的输出参数是 -c:v libwebp -frames:v 1 -f webp pipe:1。检查对应版本的封装代码后，可以看到先写占位长度、在结尾定位到头部回填的处理。在这次 5.1.9 的构建、参数和较大样本组合下，最终输出未得到正确长度，小样本却没有暴露问题。FFmpeg 5.1.9 的 webpenc.c可用于对照这条路径。

FFmpeg 当前源码已经包含在单帧 flush 时计算头部长度、无需再 seek 的路径。管道输出是否正确，取决于版本和实际执行分支；这次零长度字段出现在上述 5.1.9 构建、参数和样本组合中。

预览只需要一帧，而这条 libwebp 编码路径产生的单帧数据已经带有完整 RIFF。修复将输出格式改为 image2pipe，避免再经过当时有问题的重新封装路径。关键参数差异如下：

1
-frames:v 1 -c:v libwebp -f webp pipe:1
2
-frames:v 1 -c:v libwebp -f image2pipe pipe:1

FFmpeg 的格式文档说明，image2pipe 面向命令输出，不展开图片文件名模式。这里仍显式限制为一帧。把多帧图片连续写入管道，并不自动得到等价的动画 WebP；动画、循环次数和时间信息需要单独验证，不能套用这次修复。

把失败样本的特征留在回归里#

修改后的真实样本输出为 46,160 字节、432×768 的 WebP，RIFF 长度正确，也能解码。冷生成约 849 毫秒，随后请求命中缓存，原文件校验值保持不变。这个时间只描述该样本，不能用来推算整个素材库的加载速度。

新增回归使用合成媒体，不依赖业务素材：一张输出大于 32 KiB 的图片、一段能产生同量级封面的视频，以及带半透明通道的图形。32 KiB 是用来覆盖当时暴露问题的输出量级，不是 WebP 协议的限制。

每个用例检查 RIFF 标记和长度、尺寸，以及真实解码后的 RGBA 字节长度，还检查第二次请求的缓存命中和原文件没有变化。半透明样本另外断言 alpha 值严格介于 0 和 255 之间；这些检查没有证明所有像素逐点等价。随后把这组编码测试接到应用镜像中运行，让验证使用镜像实际携带的 FFmpeg，而不只依赖开发机的版本。

修复当天已合入主线，镜像内编码验收通过；生产部署状态尚未核实。

这次之后，媒体转换的检查多了一层：先确认输出结构，再尝试解码，最后在实际应用镜像中跑同样的回归。小图能显示，只能证明小图这条路径；原样留下较大输出和透明通道的测试，才更容易发现环境升级或封装方式变化带来的回归。