4. 滤镜链错误：从“Filter not found”到内存崩溃

滤镜链，是 FFmpeg 里最灵活也最容易翻车的地方。我见过不少新手，命令行写了一大串滤镜，一跑就报错，然后整个人就懵了。今天咱们就把滤镜链常见的四种死法——找不到滤镜、参数类型搞错、图解析失败、内存撑爆——一个一个拆开讲。

4.1 “Filter not found”——滤镜不存在？先查名字和版本

这个报错太经典了。你写了个 ffmpeg -i input.mp4 -vf "myfilter" output.mp4，然后 FFmpeg 甩你一句：Filter 'myfilter' not found。为什么会这样？

说白了，FFmpeg 没找到这个名字的滤镜。原因无非三个：

• 拼写错了——比如把 scale 写成 scal，把 trim 写成 trime。我刚开始用的时候，把 overlay 写成了 overlay（少了个 e），愣是找了十分钟。
• 版本不支持——有些滤镜是后来才加的。比如 deinterlace_qsv 是 Intel QSV 专属滤镜，老版本 FFmpeg 根本没有。
• 编译时没开启——你用的 FFmpeg 是精简版，很多滤镜被砍掉了。比如 libx264 编码器没编译进去，你用 h264_qsv 就会报错。

举个例子，你想用 drawtext 滤镜加字幕：

ffmpeg -i input.mp4 -vf "drawtext=text='Hello':fontsize=24" output.mp4

如果报 Filter 'drawtext' not found，那大概率是你的 FFmpeg 没编译 --enable-libfreetype。解决方案？要么重新编译，要么换个滤镜实现。

报错信息	常见原因	快速排查
Filter 'xxx' not found	拼写错误 / 版本不支持 / 未编译	ffmpeg -filters | grep xxx
No such filter: 'xxx'	滤镜名写错或格式不对	检查大小写和下划线
Unable to find a suitable output format	滤镜输出格式不匹配	检查滤镜链的输入输出格式

4.2 滤镜参数类型错误——数字写成字符串，立马翻车

滤镜参数是有类型的。有的参数要整数，有的要浮点数，有的要布尔值。你给错了，FFmpeg 不会帮你自动转换，直接报错。

我记得有一次，我想用 scale 滤镜把视频缩放到 1280x720：

ffmpeg -i input.mp4 -vf "scale=1280:720" output.mp4

结果报了个 Invalid value '1280:720' for parameter 'w'。我当时就纳闷了，这参数不是这么写的吗？后来才发现，scale 滤镜的参数分隔符是冒号，但 w 和 h 之间要用冒号没错，可如果你写成 scale=1280:720，FFmpeg 会把 1280:720 整个当成 w 的值。正确写法是：

ffmpeg -i input.mp4 -vf "scale=w=1280:h=720" output.mp4

或者用简写：

ffmpeg -i input.mp4 -vf "scale=1280:-1" output.mp4

这里 -1 表示自动计算高度，保持宽高比。

常见的参数类型错误：

• 整数写成浮点数——比如 fps=fps=24.5，但 fps 参数只接受整数。
• 布尔值写成字符串——比如 reverse=1 写成 reverse=true，有些滤镜不认。
• 时间格式写错——比如 trim=start=10 写成 trim=start=10s，trim 滤镜只接受秒数或时间戳。

4.3 滤镜图解析失败——语法错一个，全链崩

滤镜图（filter graph）是多个滤镜串联或并联的复杂结构。解析失败，说白了就是你的语法写错了，FFmpeg 看不懂。

举个例子，你想先缩放再裁剪：

ffmpeg -i input.mp4 -vf "scale=1280:720,crop=640:480" output.mp4

这个没问题。但如果你写成：

ffmpeg -i input.mp4 -vf "scale=1280:720, crop=640:480" output.mp4

注意，crop 前面多了个空格。有些版本的 FFmpeg 会报 Failed to configure output pad。为什么？因为滤镜图解析器把空格当成了分隔符，它以为 scale=1280:720, 是一个滤镜，然后 crop=640:480 是另一个，但逗号后面不能有空格。

更复杂的滤镜图，比如用分号（;）连接多个输出流：

ffmpeg -i input.mp4 -filter_complex "[0:v]split[base][over];[base]scale=1280:720[scaled];[scaled][over]overlay=10:10" output.mp4

这里分号表示滤镜链的分支。如果你写错了标签名，比如 [scaled] 写成 [scale]，FFmpeg 会报 Cannot find a matching stream for unlabeled input pad。说白了，就是标签对不上。

语法错误	报错示例	修复方法
逗号后有多余空格	Failed to configure output pad	去掉空格
标签名写错	Cannot find a matching stream	检查标签名是否一致
分号位置错误	Filtergraph parse error	确保分号用于分支，不是串联
缺少输出标签	Output pad not connected	给每个分支加上输出标签

4.4 内存不足导致的滤镜崩溃——别小看资源问题

滤镜链吃内存，尤其是复杂滤镜图。你想想看，一个 4K 视频，先缩放再裁剪再叠加字幕，中间要缓存好几帧数据。如果内存不够，FFmpeg 直接崩溃，连个像样的报错都不给。

我记得有一次，我在服务器上跑一个 overlay 滤镜，视频是 4K 的，叠加了 5 个图片水印。结果跑了 10 秒就崩了，日志里只有 Killed。后来查系统日志才发现是 OOM（Out of Memory）被杀掉了。

怎么避免内存崩溃？

• 降低分辨率——先缩放到 1080p 再做其他滤镜。
• 减少滤镜数量——能不用的滤镜就别用，尤其是 overlay、split 这种吃内存的。
• 增加交换空间——临时方案，但能救急。
• 使用 -threads 限制线程数——线程太多也会吃内存。

举个例子，如果你必须用复杂滤镜图，可以这样优化：

ffmpeg -i input.mp4 -vf "scale=1920:1080,setpts=0.5*PTS" -threads 2 output.mp4

这里 -threads 2 限制只用两个线程，减少内存占用。虽然速度慢点，但至少不会崩。

4.5 滤镜链错误排查流程图

下面这张图，是我自己总结的滤镜链错误排查流程。遇到问题，按这个顺序查，基本能解决 90% 的情况。

4.6 实战：修复一个真实的滤镜链报错

咱们来看一个真实案例。假设你有这样一个命令：

ffmpeg -i input.mp4 -vf "scale=1920:1080,drawtext=text='Hello':fontsize=24:fontcolor=white" output.mp4

报错信息是：Filter 'drawtext' not found。按照上面的流程图：

1. 第一步：查滤镜名——跑 ffmpeg -filters | grep drawtext，发现没有结果。说明 FFmpeg 没编译这个滤镜。
2. 第二步：查参数类型——既然滤镜都不存在，参数类型就不用查了。
3. 第三步：查滤镜图语法——语法没问题，但滤镜不存在，语法再对也没用。
4. 第四步：查内存——跟内存无关。

解决方案：要么重新编译 FFmpeg 加上 --enable-libfreetype，要么换个滤镜实现。比如用 subtitles 滤镜加载字幕文件：

ffmpeg -i input.mp4 -vf "scale=1920:1080,subtitles=subtitle.srt" output.mp4

或者干脆用 ffmpeg -filters 找一个替代滤镜。嗯，这里要注意，drawtext 不是唯一的选择。