HandBrakeCLI在PHP中调用失败主因是路径、权限或环境隔离问题；须用绝对路径调用，确保Web用户有文件读写权，禁用SELinux/AppArmor，安全传参需escapeshellarg()，批量任务应通过JSON队列交由HandBrake自动串行执行。
HandBrakeCLI 在 PHP 中调用失败的常见原因
PHP 调用 HandBrakeCLI 失败，90% 是因为路径、权限或环境隔离问题，不是 PHP 代码写得不对。Web 服务器（如 Apache/Nginx）运行的 PHP 进程通常以低权限用户（www-data 或 _www）执行，无法访问你终端里能直接运行的 HandBrakeCLI —— 它可能只装在你的用户 home 目录，或没加进系统 PATH。
- 先在终端确认命令可用：
which HandBrakeCLI或/usr/bin/HandBrakeCLI --version，记下完整路径（比如/usr/local/bin/HandBrakeCLI） - PHP 中必须用绝对路径调用，不能只写
HandBrakeCLI - 确保 Web 服务器用户对输入文件有读取权限，对输出目录有写入权限（
chmod -R 755 /path/to/output，必要时chown www-data:www-data） - 禁用 SELinux 或 AppArmor（Linux）或检查 macOS Gatekeeper 日志，它们会静默拦截 CLI 执行
PHP exec() 调用 HandBrakeCLI 的安全写法
直接拼接用户输入进 exec() 是高危操作，HandBrake 输入路径含空格、单引号、括号时极易被注入。必须过滤、转义、限定范围。
- 输入路径用
realpath()标准化，并限制在白名单目录内：if (strpos($input_path, '/var/www/videos/') !== 0) die('Invalid path'); - 用
escapeshellarg()包裹每个参数，包括输入、输出、预设名：escapeshellarg('/usr/local/bin/HandBrakeCLI') - 不要用
shell_exec()捕获全部输出，改用exec($cmd, $output, $return_code)，检查$return_code === 0判断成功 - 加超时限制：
set_time_limit(300)，避免一个卡死任务拖垮整个 PHP 进程
批量队列用 JSON 文件中转，别硬写循环
PHP 里用 for 循环反复调 exec() 启 HandBrake 任务，容易资源争抢、日志混乱、失败难追踪。正确做法是让 PHP 生成标准 HandBrake 队列 JSON，再交由 HandBrakeCLI --queue-import-file 一次性加载。
- 构造符合 HandBrake JSON 队列格式的数组，关键字段：
Path（绝对路径）、Preset（字符串，如"Fast 1080p30"）、Destination（输出路径，确保 .mp4 或 .mkv 后缀） - 用
json_encode($queue_data, JSON_UNESCAPED_UNICODE)生成文件，保存为/tmp/hb_queue_123.json - 执行：
/usr/local/bin/HandBrakeCLI --queue-import-file /tmp/hb_queue_123.json --run-queue - HandBrake 自动串行执行，PHP 只需监听 JSON 文件是否被清空或检查日志，不参与调度逻辑
输出日志和错误捕获必须分开处理
HandBrakeCLI 把进度输出到 stderr，成功完成也返回 0，但中间报错（如“no valid title found”）不会中断进程，仅写 stderr —— 如果你不显式捕获，这些关键信息就丢了。
立即学习“PHP免费学习笔记（深入）”；
- 调用时重定向：
$cmd .= ' 2>&1 > /dev/null'是错的；正确是$cmd .= ' 2> /var/log/hb_job_123.err 1> /var/log/hb_job_123.log' - 错误日志里重点 grep：
"Error:"、"No title found"、"Invalid preset"、"Permission denied" - 不要依赖
exec()返回的$output数组看进度，HandBrake 的实时进度是动态覆盖行，PHP 拿到的是最终几行，意义不大
