PHP视频文件处理错误捕获与日志记录调试技巧

经验丰富的 PHP 开发者都知道，$_FILES['video']['error'] 是上传失败时第一道防线。但它只返回一个整数，比如 UPLOAD_ERR_INI_SIZE（值为 1），具体是因为磁盘满了、扩展名被拒还是 upload_max_filesize 超限，单看数字很难判断。靠猜测调试效率太低，需要一套清晰的排查流程。

上传成功后也不能掉以轻心，必须用 ffprobe 验证视频是否真的有效，否则光是检查 MIME 类型很容易被伪造的 .mp4 文件绕过。

video_upload 失败时怎么捕获具体错误

处理视频文件上传失败，$_FILES['video']['error'] 是第一道判断依据，但它只返回整数错误码，不带上下文。直接 var_dump($_FILES) 往往看不出问题根源——比如磁盘满、扩展名被拒、upload_max_filesize 超限，这些都映射到同一个 UPLOAD_ERR_INI_SIZE（值为 1）。

实操建议：

• 先查 $_FILES['video']['error'] 值，对照 PHP 官方常量：UPLOAD_ERR_OK、UPLOAD_ERR_INI_SIZE、UPLOAD_ERR_FORM_SIZE、UPLOAD_ERR_PARTIAL、UPLOAD_ERR_NO_FILE、UPLOAD_ERR_NO_TMP_DIR、UPLOAD_ERR_CANT_WRITE、UPLOAD_ERR_EXTENSION
• 若为 UPLOAD_ERR_INI_SIZE 或 UPLOAD_ERR_FORM_SIZE，必须同步检查 ini_get('upload_max_filesize') 和表单隐藏域 MAX_FILE_SIZE 是否一致且足够大
• 若为 UPLOAD_ERR_CANT_WRITE，大概率是临时目录（sys_get_temp_dir()）无写权限或空间不足，不是视频本身问题
• 上传成功后，立刻用 getimagesize($tmp_path) 或 ffprobe（需系统命令）验证是否真为有效视频，避免恶意伪造的 .mp4 文件绕过 MIME 检查

ffmpeg 执行失败如何获取详细报错

用 exec() 或 shell_exec() 调 ffmpeg 处理视频时，错误常静默丢失。默认 stderr 不被捕获，$output 只含 stdout，而 ffmpeg 把关键错误（如编解码器不支持、文件损坏）全打在 stderr 上。

实操建议：

• 务必重定向 stderr 到 stdout：exec("ffmpeg -i '$input' -c:v libx264 '$output' 2>&1", $output, $return_code)，否则 $output 是空的
• $return_code 非 0 才代表失败，但仅靠它无法定位原因；必须看 $output 内容，里面包含 ffmpeg 原始错误行，例如 "Invalid data found when processing input" 或 "Unknown encoder 'libx264'"
• 生产环境禁用 exec() 时，改用 proc_open() 精确控制 stdin/stdout/stderr 流，并设置超时（视频转码可能卡住），避免进程僵尸化
• 不要依赖 mime_content_type() 判断视频格式——它只看文件头，对剪辑过的 MP4 或 WebM 容易误判；真正校验应调用 ffprobe -v quiet -show_entries format=duration -of default "$file" 并解析输出

PHP 里怎么记录视频处理全流程日志

单一 error_log() 调用无法支撑视频任务排错：你得知道“哪个用户、上传了什么文件、在哪个环节（上传/校验/转码/截图）、耗时多久、返回什么错误”。硬编码拼接字符串易漏字段、难解析。

实操建议：

• 用结构化日志：至少包含 timestamp、user_id、file_name、stage（如 'upload'/'validate'/'transcode'）、duration_ms、error（如有）、extra（如 ffmpeg 返回码、临时路径）
• 避免直接写文件，优先用 MonologLogger + StreamHandler，格式设为 JsonFormatter，方便 ELK 或 grep 解析
• 关键节点手动打点：上传后记一条，ffprobe 校验后记一条，ffmpeg 开始前记一条，结束后再记一条——别等最后统一记，中间挂了就断档
• 日志路径要有隔离：按日期分目录，如 /var/log/video/2026-06-18.log，防止单文件过大；同时确保 www-data 用户对该路径有写权限（常见坑：log 目录属主是 root）

set_error_handler 对视频操作无效？为什么

set_error_handler() 捕获不了视频处理中的多数问题，因为它的作用域仅限于 PHP 运行时警告（E_WARNING）、通知（E_NOTICE）等，而视频相关错误基本不在这个范畴：

实操说明：

• $_FILES 错误是 CGI 协议层返回的整数，不是 PHP 错误，set_error_handler 完全收不到
• ffmpeg 子进程崩溃、超时、信号终止（如 SIGKILL），PHP 层只拿到一个非零 $return_code，不会触发任何 PHP 错误
• GD 或 Imagick 处理视频帧截图时抛出的 Exception，属于异常而非错误，必须用 try-catch，不是 set_error_handler 的管辖范围
• 真正该用 set_error_handler 的地方，其实是自定义函数里主动 trigger_error()——比如你封装的 validateVideoDuration() 发现时长超限，可 trigger_error("视频时长超出30分钟限制", E_USER_WARNING)，这时才能被捕获

视频处理链条长、跨进程、强依赖外部工具，错误分散在协议层、系统层、子进程层和应用逻辑层——没有银弹，得一层层加防护和日志，漏掉任意一环，排查时就只能靠猜。