FFmpeg 9.0加水印三大核心坑：字体路径须绝对且无中文空格；movie+overlay需setpts对齐PTS避免偏移；boxcolor等颜色值必须带0x前缀，多分辨率需scale2ref联动缩放。
FFmpeg 9.0（2026年9月发布）加水印不是“换版本就能跑通”，核心坑集中在三点：字体路径解析逻辑变更、drawtext默认色彩空间强制为yuva420p、以及movie+overlay链路中对PTS/DTS对齐的校验更严格——不处理，80%的命令会静默失败或水印错位。
drawtext字体加载失败：不是没装字体，是路径解析变了
FFmpeg 9.0 默认禁用 FontConfig 自动发现机制，fontfile必须是绝对路径，且不能含中文或空格。相对路径（如./fonts/arial.ttf）会直接报Unable to load font file，不提示具体原因。
- 验证方式：
ffprobe -v quiet -show_entries format_tags=fonts "test.mp4"看是否识别到字体（实际无效，仅作参考）；更可靠的是用ls -l /path/to/your/font.ttf确认权限和路径 - 正确写法：
fontfile=/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf，推荐用系统自带的 DejaVu 或 Noto 系列，避免版权风险 - Windows 下注意反斜杠转义：应写成
fontfile=C:/Windows/Fonts/arial.ttf，而非C:\Windows\Fonts\arial.ttf - 若必须用自定义字体，先用
fc-list | grep -i "yourfont"查系统注册名，再用fontfile指向其物理路径
overlay水印偏移/闪烁：PTS基准未对齐是主因
在 FFmpeg 9.0 中，movie输入源若无明确start_time元数据（比如 PNG 水印图），其 PTS 默认从 0 开始，而主视频可能有非零start_time（常见于手机录制 MP4）。结果就是 overlay 帧在时间轴上“卡顿”或整段漂移。
- 强制对齐方法：在
movie后加setpts=PTS-STARTPTS，例如movie=logo.png[wm]; [wm]setpts=PTS-STARTPTS[wm2] - 更稳妥方案：用
fps=30固定水印帧率，避免 VFR 视频引发的 PTS 跳变：movie=logo.png,fps=30,format=yuva420p[wm] - 检查原始视频时间基准：
ffprobe -v quiet -show_entries stream=start_time,input_filename=test.mp4，对比start_time是否为 0.0
boxcolor背景色显示异常：十六进制格式必须带 0x 前缀
FFmpeg 9.0 对颜色参数校验更严格。boxcolor=blue 仍可工作，但 boxcolor=#0000FF 或 boxcolor=0000FF 会静默忽略，导致背景框透明或默认白色——这不是 bug，是解析失败后 fallback 行为。
- 必须写成：
boxcolor=0x0000FF（纯蓝）、boxcolor=0x0000FFCC（带透明度，AA=0xCC≈80%不透明） - alpha 通道值范围是 0x00–0xFF，不是 0–255 十进制；
0x0000FF80≠0x0000FF50，别手抖少输一位 - 调试技巧：先去掉
box=1，单独测试fontcolor=0xFF0000是否生效，确认颜色解析链正常
多分辨率批量处理时水印比例失真：别硬写像素值
用固定 x=100:y=100 给 720p 和 4K 视频加水印，结果是 4K 上水印小得看不见，720p 上又过大。FFmpeg 9.0 未提供内置缩放函数，需靠 scale2ref 手动联动。
- 正确姿势：把水印图先缩放到目标视频宽高的 8%，再 overlay：
[0:v][1:v]scale2ref=w=iw*0.08:h=ih*0.08[wm][base];[base][wm]overlay=x=W-w-20:y=H-h-20 - 关键点：
W和H是主视频宽高变量，w和h是水印图当前宽高，必须用scale2ref同步，否则变量不生效 - Shell 脚本中慎用双引号包裹 filter_complex：变量如
$width在双引号内会被 shell 展开，导致 filter 解析失败；统一用单引号 + 拼接
最易被忽略的一点：FFmpeg 9.0 的 libsvtav1 编码器在启用 -c:v libsvtav1 时，会绕过部分 overlay 滤镜的 alpha 处理，导致 PNG 水印边缘发灰。生产环境若用 AV1 编码，务必加 -vf "format=yuva420p" 强制色彩空间，别依赖默认行为。
