ffmpeg php 包仅是命令行工具的封装，需先安装系统级ffmpeg并确保web进程有执行权限；截图需注意关键帧限制，转码需捕获stderr并设超时；php-fpm环境需配置path或显式指定ffmpeg路径。
FFmpeg PHP 包不能直接“转码”或“截图”
Composer 引入的 php-ffmpeg/php-ffmpeg 只是一个面向对象的封装层，它本身不带 FFmpeg 二进制程序。如果你只执行 composer require php-ffmpeg/php-ffmpeg，然后调用 $video->filters()->resize() 或 $video->frame()，大概率会遇到 Unable to load FFmpeg in /usr/bin/ffmpeg 这类错误。
真正干活的是系统级的 ffmpeg 命令行工具，PHP 包只是拼命令、传参数、读输出。所以第一步永远是确认本地或服务器是否已安装且可执行：
- 运行
which ffmpeg或ffmpeg -version，必须有响应 - Web 进程（如 www-data、nginx 用户）必须有权限执行该二进制文件
- 如果用 Docker，需在容器内安装
ffmpeg，不能只装 PHP 包 - Windows 下注意路径含空格（如
C:Program Files fmpegin fmpeg.exe）必须用引号包裹，PHP 包默认不加，得手动设new FFMpegFFMpeg(..., ['ffmpeg.binaries' => '"C:\Program Files\ffmpeg\bin\ffmpeg.exe"'])
截图失败常见于时间点精度与帧类型
调用 $video->frame(FFMpegCoordinateTimeCode::fromSeconds(10)) 不一定真能截出第 10 秒那帧——FFmpeg 默认只在关键帧（I-frame）处截图，而关键帧间隔可能是 2 秒甚至更长。如果第 10 秒恰好落在 P/B 帧上，它会自动往前找最近的关键帧（比如第 9.8 秒），导致截图时间偏移。
要严格按秒截，必须强制解码到指定时间点：
- 在
frame()前加$video->filters()->forceKeyFrames('expr:gte(t,n_forced*2)')不起作用，这是给编码用的 - 正确做法是改用
FFMpegFormatVideoX264等格式时设置setAdditionalParameters(['-ss', '10', '-vframes', '1'])，但注意-ss放在输入前（快）还是输出后（准），前者快但可能不准，后者慢但精确 - 更稳妥：先用
-ss 10 -i input.mp4 -vframes 1 -y out.jpg手动测试，确认结果符合预期再映射到 PHP 包逻辑中
转码卡在“无日志、无报错、进程僵死”
PHP 调用 FFmpeg 转码时，如果没设超时或没捕获 stderr，很容易出现脚本挂起、CPU 占满却无任何输出的情况。这不是 PHP 包的 bug，而是 FFmpeg 遇到损坏帧、不支持编码器、或硬件加速冲突时的典型表现。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
排查重点不是 PHP 代码，而是底层命令行为：
- 用
$ffmpeg->getCommand($video, $format)打印出实际执行的命令，复制到终端手动跑一遍，观察完整 stderr 输出 - 常见陷阱：
-c:v libx265在没编译 x265 的 FFmpeg 上直接静默失败；-hwaccel cuda在没 GPU 或驱动不匹配时卡住 - PHP 中务必设置超时：
$ffmpeg->open($path)->save($format, $outPath, true, ['timeout' => 300])，第 3 个参数true表示启用超时（默认 false） - 避免在 Web 请求中长时间转码，更适合丢进队列（如 Redis + Supervisor）后台处理
PHP-FPM 下的环境变量与 PATH 隔离问题
你在 CLI 下 ffmpeg -version 正常，但 Web 页面里 exec('ffmpeg -version') 报 command not found，大概率是 PHP-FPM 使用了精简的 env，PATH 被重置为 /usr/local/bin:/usr/bin:/bin，而你把 ffmpeg 装在 /opt/ffmpeg/bin/。
不要在 PHP 里硬编码绝对路径去绕过，容易埋坑：
- 在 PHP-FPM pool 配置里加
env[PATH] = /opt/ffmpeg/bin:/usr/local/bin:/usr/bin:/bin，然后重启 fpm - 或者统一用
which ffmpeg查路径，再传给FFMpegFFMpeg::create([...])的ffmpeg.binaries选项 - 别依赖
$_ENV['PATH']—— FPM 默认不继承父进程环境变量，getenv('PATH')往往是空的
真正难的从来不是写几行 PHP 调用，而是让那个黑盒命令行工具，在各种环境里稳定吐出你想要的帧和码流。每台服务器的 FFmpeg 编译选项、GPU 支持、权限模型都不同，手工验证命令比盲调 PHP 参数重要得多。
