PHP-FFMpeg必须用Composer安装php-ffmpeg/php-ffmpeg，禁用已废弃的ffmpeg-php扩展；需显式指定ffmpeg/ffprobe二进制路径、设置timeout和threads参数，并传入FormatInterface对象（如X264）才能正常转码。
PHP-FFMpeg扩展包必须用Composer安装，不能装ffmpeg-php
直接装 ffmpeg-php 扩展在现代 PHP（尤其是 7.4+ 和 PHP 8.x）中基本不可行：它早已停止维护，不兼容 ZTS 线程安全模式，且与当前主流 SAPI（如 FPM、CLI）存在符号冲突。你看到的“安装成功”大概率是编译通过但运行时 segmentation fault 或 undefined symbol 错误。
正确路径只有一条：composer require php-ffmpeg/php-ffmpeg。这个包是纯 PHP 实现，不依赖 C 扩展，所有音视频操作都通过调用系统级 ffmpeg 和 ffprobe 二进制完成，兼容性好、调试直观。
- 安装后自动拉取
alchemy/binary-driver，负责进程启动、参数拼接和超时控制 - 不修改 PHP 配置（
php.ini），也不需要extension=ffmpeg.so - 如果你在 ThinkPHP、Laravel 或其他框架里使用，注意命名空间前缀：例如 TP8 要写
\FFMpeg\FFMpeg::create()，否则会报Class 'FFMpeg\FFMpeg' not found
ffmpeg 和 ffprobe 二进制文件必须可执行，且路径要显式指定
php-ffmpeg/php-ffmpeg 默认会尝试从 $PATH 查找 ffmpeg 和 ffprobe，但生产环境（尤其是宝塔、Docker、非 root 用户部署）几乎总是失败——因为 Web 进程用户（如 www）的 PATH 和你 SSH 登录时不同，which ffmpeg 返回空。
别信“只要终端能跑，PHP 就能跑”的直觉。验证方式很简单：php -r "echo shell_exec('which ffmpeg 2>&1');"。如果没输出，说明 PHP 进程根本看不到它。
立即学习“PHP免费学习笔记（深入）”；
- 先确认二进制真实路径：
sudo find / -name ffmpeg -type f -executable 2>/dev/null，常见位置有/usr/bin/ffmpeg、/usr/local/bin/ffmpeg、/opt/ffmpeg/bin/ffmpeg - 创建实例时必须传入完整路径：
FFMpeg::create(['ffmpeg.binaries' => '/usr/local/bin/ffmpeg', 'ffprobe.binaries' => '/usr/local/bin/ffprobe']) - 权限问题常被忽略：确保 Web 用户对该路径有
x（执行）权限，不是只读；若二进制在/root下，Web 进程绝对无法访问
timeout 和 ffmpeg.threads 参数不设就会卡死或超时失败
视频转码是耗时操作，而 PHP-FPM 默认 request_terminate_timeout 是 30 秒，CLI 模式下 max_execution_time 默认 0（不限制），但 php-ffmpeg 自身有独立超时机制。不显式配置，小视频可能侥幸成功，一旦处理 1080p 或长视频，大概率触发 RuntimeException: Process timed out。
-
timeout是单个 FFmpeg 进程最大运行秒数，建议按业务场景设为 600～3600（10 分钟到 1 小时） -
ffmpeg.threads控制编码线程数，默认是 0（自动），但在多核服务器上设为 CPU 核心数（如 4 或 8）能明显提速，尤其对libx264编码 - 注意：线程数不是越多越好，超过物理核心反而因上下文切换拖慢；若服务器内存紧张（
save() 方法链式调用必须加格式对象，不能直接传字符串路径
新手最常写的错代码：$video->save('output.mp4') —— 这会直接抛出 Fatal error: Uncaught TypeError，因为 save() 第一个参数必须是实现了 FFMpeg\Format\FormatInterface 的对象，比如 X264、WMV 或 WebM。
漏掉格式对象，等于让 FFmpeg 不知道用什么编码器、什么码率、是否保留音频，它不会“智能猜测”，而是直接拒绝执行。
- 基础 MP4 输出必须配编码器：
$format = new FFMpeg\Format\Video\X264('aac'); - 记得设置关键参数，否则输出质量极差：
$format->setKiloBitrate(1500)->setAudioKiloBitrate(192) - 如果只是提取帧或音频，要用对应类：
$video->frame(...)->save('thumb.jpg')或$video->filters()->extractAudio()->save(...)
LoggerInterface，把 exec 命令原样打出来，再手动复制到终端执行——很多问题（比如缺少 libx264 支持、GPU 驱动未加载、输入文件损坏）只在命令行执行时才暴露错误信息。 
