直接用 composer require php-ffmpeg/php-ffmpeg 安装 PHP 封装库，但必须单独安装系统级 ffmpeg 和 ffprobe 命令行工具并确保其在 PATH 中或显式指定路径，否则初始化失败。
直接用 composer require 安装 php-ffmpeg 包就行
Composer 本身不“安装 FFMpeg”，它只负责安装 PHP 封装库 php-ffmpeg/php-ffmpeg。真正的音视频处理能力依赖系统级的 ffmpeg 命令行工具——这个必须单独安装，否则 PHP 库调用会报错（比如 Unable to load FFProbe 或 ffprobe not found）。
执行这行命令即可引入 PHP 封装层：
composer require php-ffmpeg/php-ffmpeg
注意：该包已放弃对 PHP 7.4 以下版本的支持；如果你用的是 PHP 8.2+，建议加 --with-all-dependencies 避免因 symfony/process 版本冲突导致安装失败。
系统必须先装好 ffmpeg 和 ffprobe 命令行工具
PHP-FFMpeg 只是调用外部命令，它默认会在 $PATH 中查找 ffmpeg 和 ffprobe。如果找不到，就会抛出异常，而不是静默降级。
立即学习“PHP免费学习笔记（深入）”；
- Linux（Ubuntu/Debian）：
sudo apt update && sudo apt install ffmpeg - macOS：
brew install ffmpeg（确保brew的 bin 目录在$PATH中） - Windows：下载静态编译版（如 https://github.com/BtbN/FFmpeg-Builds/releases），解压后把
bin/目录加进系统环境变量PATH
装完务必验证：
ffmpeg -version
ffprobe -version
两个命令都得能正常返回版本号。少一个，PHP 库就可能初始化失败。
初始化时指定二进制路径可绕过 PATH 查找
有些共享主机或容器环境无法修改 PATH，或者你只想用某个特定版本的 ffmpeg（比如自己编译的带 libx265 支持的），这时可以在创建 FFMpeg 实例时显式传入路径：
$ffmpeg = FFMpeg\FFMpeg::create([
'ffmpeg.binaries' => '/opt/my-ffmpeg/bin/ffmpeg',
'ffprobe.binaries' => '/opt/my-ffmpeg/bin/ffprobe',
]);
注意点：
- 路径必须指向可执行文件，不是目录
- PHP 进程需有对应路径的读取和执行权限（尤其在 SELinux 或 Docker 中）
- 不要漏掉
ffprobe.binaries——很多格式探测、时长获取功能都依赖它，缺了会直接 throw Exception
常见报错和对应检查项
运行时报错往往不是代码问题，而是环境链路断了。遇到失败先按顺序排查：
-
FFMpeg\Exception\RuntimeException: Unable to probe /path/to/file.mp4→ 检查ffprobe是否可用、文件路径是否正确、PHP 是否有读取权限 -
FFMpeg\Exception\RuntimeException: Encoding failed→ 查看 ffmpeg 输出日志（用setLogLevel(FFMpeg\FFProbe::LOG_DEBUG)），大概率是编码器不支持（如没装libx264）或参数写错（比如-c:v libx265但系统 ffmpeg 不带 x265） -
Failed loading required extension: gd or imagick→ 截图功能需要图像扩展，不是核心依赖，按需安装gd或imagick即可 - 超时：大文件转码卡住 → 默认超时是 300 秒，用
setTimeOut(0)关闭限制（生产环境慎用）
真正容易被忽略的是：ffprobe 和 ffmpeg 的版本要尽量匹配，混用不同大版本（如 ffmpeg 5.x + ffprobe 6.x）可能导致解析行为不一致，尤其在处理 HDR 元数据或新封装格式时。
