用 ffmpeg 命令行截帧最可靠，PHP 应调用 exec 或 shell_exec 执行 ffmpeg 而非依赖废弃扩展；需用 escapeshellarg() 防注入、-ss 10 跳中段避黑场、-vf 保宽高比、2>&1 捕获 stderr，并检查路径、权限、版本及系统资源。
用 ffmpeg 命令行直接截帧最可靠
PHP 调用 exec 或 shell_exec 执行 ffmpeg 是生成封面图的首选方式，比 PHP 自己解析视频流稳定得多。FFmpeg 本身对关键帧、时间精度、缩放质量控制得更细，PHP 扩展（如 ffmpeg-php）早已废弃且不兼容新版 PHP。
常见错误是直接取第 1 帧（-ss 0 -vframes 1），但很多视频首帧是黑场或编码器填充帧；应跳到视频中段再截，比如 -ss 10（第 10 秒），并加 -vf "scale=320:-1:force_original_aspect_ratio=decrease" 保证宽高比。
实操建议：
- 先用
ffprobe获取视频时长：ffprobe -v quiet -show_entries format=duration -of csv=p=0 input.mp4，避免硬写-ss 10导致越界 - 加上
-y参数防止交互式覆盖提示阻塞 PHP 进程 - 输出格式统一用
.jpg，别用.png——部分服务器 GD 库不支持透明通道，但封面图不需要 alpha - 务必检查
exec返回值和$output内容，ffmpeg出错时通常不抛异常，只写 stderr
shell_exec 中必须过滤输入路径防命令注入
用户上传的视频文件名若含空格、分号、反引号等字符，直接拼进 shell_exec("ffmpeg -i $path ...") 会导致命令被截断甚至执行任意命令。不能靠前端校验，后端必须处理。
立即学习“PHP免费学习笔记（深入）”；
正确做法是用 escapeshellarg() 包裹所有外部变量：
php
$input = escapeshellarg($_FILES['video']['tmp_name']);
$output = escapeshellarg('/var/www/thumbs/' . uniqid() . '.jpg');
$cmd = "ffmpeg -i $input -ss 10 -vframes 1 -q:v 2 -vf \"scale=320:-1:force_original_aspect_ratio=decrease\" $output 2>&1";
$result = shell_exec($cmd);
注意：escapeshellarg() 会把路径变成带单引号的字符串，所以不要自己再加引号；2>&1 必须带上，否则错误信息看不到。
容易踩的坑：
- Windows 环境下
escapeshellarg()行为不同，建议统一部署在 Linux 服务器上处理视频 - 如果
$input是相对路径（比如uploads/xxx.mp4），确保 PHP 当前工作目录正确，或一律用绝对路径 - 某些共享主机禁用
shell_exec，需改用proc_open并捕获 stderr 流
PHP 需要设置超时和内存限制
一个 500MB 的 MP4 截帧可能耗时 3–8 秒，PHP 默认 max_execution_time=30 虽然够用，但 FFmpeg 进程本身可能被系统 OOM killer 杀掉，尤其在低配 VPS 上。
必须显式调优：
- 调大
set_time_limit(120)，留出 FFmpeg 启动和 I/O 时间 - 关闭输出缓冲：
ob_end_flush()，避免大块 stderr 输出卡住响应 - 不要用
exec()+getmypid()去 kill 进程——PHP 子进程无法可靠回收，应依赖 FFmpeg 自身完成 - 检查
memory_limit是否设为-1或足够大（至少 128M），虽然 FFmpeg 自己吃内存，但 PHP 进程若同时读取大日志也会爆
性能影响明显：未设 set_time_limit 时，大视频经常返回空结果却无报错；memory_limit 不足则 shell_exec 直接返回 null。
生成失败时优先查 ffmpeg 的 stderr 输出
PHP 层面看到 $result === null 或空字符串，不代表 FFmpeg 没运行——大概率是它报错了但你没捕获 stderr。很多线上问题卡在这一步，反复改 PHP 逻辑却忽略真正源头。
调试建议：
- 把
2>&1改成2>/tmp/ffmpeg_err.log单独记录错误，再用file_get_contents('/tmp/ffmpeg_err.log')读取 - 典型错误包括：
No such file or directory（路径不存在）、Invalid data found when processing input（视频损坏）、Unknown encoder 'libx264'（FFmpeg 编译缺失 codec） - 如果报
Permission denied，不是 PHP 权限问题，而是 FFmpeg 二进制文件没可执行权限：chmod +x /usr/bin/ffmpeg - 用
which ffmpeg和ffmpeg -version在 PHP 里执行一次，确认环境变量和版本一致
最常被忽略的是 FFmpeg 版本差异：-vf scale 在 3.x 和 4.x 行为略有不同，而某些 Docker 镜像自带的是精简版，缺 libswscale 就会静默失败。
