php调用ffmpeg加水印失败，90%源于参数拼接错误、路径失效或坐标逻辑错误；需检查命令完整性、用escapeshellarg()转义路径、区分w/w/h/h大小写、预处理旋转/sar、调整超时与权限，并优先用ffprobe确认媒体真实参数。
PHP调用FFmpeg给视频加水印失败，90%不是FFmpeg本身的问题，而是PHP层参数传错、路径失效或坐标逻辑崩了——直接看报错再动手改，别猜。
报错“Unable to find a suitable output format for 'overlay'”
这是FFmpeg命令被PHP当字符串字面量执行时最典型的语法断裂。根本原因：PHP拼接命令时漏了空格、引号嵌套错乱，或shell_exec()没转义特殊字符。
- 检查你拼出的完整命令是否能在终端直接运行（把
exec()里的字符串拷出来，粘贴到服务器命令行试） - 用
escapeshellarg()包裹所有含路径/文件名的变量，比如escapeshellarg($video_path)，不能只对主路径做，水印图路径也必须包 - 避免用双引号拼接含$变量和单引号的FFmpeg表达式，例如
"-vf 'overlay=x=W-w-10:y=H-h-10'"在PHP里极易被提前解析——改用单引号字符串 + 变量拼接，或直接用sprintf() - 确认FFmpeg版本 ≥ 4.0，老版本不支持
W/w/H/h这种动态变量写法，会直接报这个错
水印位置偏移或变形，但命令无报错
命令跑通、视频能播、水印却“飞了”——这是overlay坐标系和媒体元数据不匹配导致的视觉错位，和PHP关系不大，但PHP调用时若没预处理就必然中招。
-
W和w大小写必须严格区分：W是主视频宽度（像素），w是水印图宽度（像素），x=W-w-10才是右下角距边10px；写成x=w-w-10结果恒为-10，水印永远贴左边界外 - 手机竖拍视频常带
rotate=90元数据，FFmpeg按原始存储尺寸计算坐标，但人眼看到的是旋转后的画面——加水印前先用-vf "transpose=1"或-noautorotate统一归一化方向 - 水印PNG若含非标准SAR（采样宽高比），和主视频不一致时，播放器会缩放渲染，造成“位置偏了”的假象——用
ffprobe查两边的sar值，不一致就用-vf "setsar=1"强制归一 - 不要用“肉眼量图”定坐标，先用
ffprobe -v quiet -show_entries stream=width,height $video_path拿到真实W/H，再用identify -format "%w x %h" watermark.png确认w/h
PHP执行后返回空、超时或内存溢出
不是FFmpeg卡死，是PHP进程被系统策略掐断了。尤其在Web环境（如Nginx+PHP-FPM）下，默认限制极严。
-
exec()类函数在FPM模式下常被禁用，检查php.ini中disable_functions是否包含exec,shell_exec,system - Web请求默认超时30秒，而1080p视频加水印可能耗时更久——在PHP脚本开头加
set_time_limit(300)，同时确认Nginx的fastcgi_read_timeout和PHP-FPM的request_terminate_timeout已同步调大 - FFmpeg本身吃内存，但PHP还额外加载整个视频帧缓冲——别用
shell_exec()捕获全部输出，改用proc_open()流式读stderr，避免stdout堆积撑爆内存 - 权限问题常表现为“静默失败”：确保PHP进程用户（如
www-data）对输入视频、水印图、输出目录均有读写权限，且ffmpeg二进制文件可执行（chmod +x /usr/bin/ffmpeg）
用php-ffmpeg库时watermark()不生效
这个封装库掩盖了底层细节，出问题反而更难定位。它内部仍走FFmpeg命令，只是帮你拼——拼错了你还不知道。
- 确认
$video->filters()->watermark()后调用了save()或frame()，否则只是声明没执行 - 库的
position参数设'relative'时，bottom/right单位是像素，但若视频有黑边或非标准分辨率，实际生效位置会漂移——优先改用'absolute'并手动算x/y - 水印图路径必须是服务器绝对路径，相对路径在CLI和Web环境下行为不一致，库不会自动
realpath() - 该库对透明PNG支持不稳定，若水印发灰或背景变黑，显式加
-vf "format=yuv420p"（通过addFilter()注入）
真正麻烦的从来不是“怎么加”，而是“为什么看起来加了却不对”。坐标大小写、旋转元数据、SAR、执行权限、超时设置——这些点散落在不同层级，漏一个就白调半天。动手前先用ffprobe看清视频底细，再让PHP老老实实传对参数，比反复改PHP逻辑管用得多。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
