PHP CLI 批量视频水印需绕过Web限制，用escapeshellarg()安全拼接路径，校验ffmpeg返回码，处理旋转/Alpha/超时等细节，并以失败为前提设计容错机制。
PHP 本身不能直接处理视频水印，必须调用
ffmpeg 命令行工具；CLI 模式下批量处理的关键不是“写得漂亮”，而是稳住超时、过滤路径、校验返回码、释放资源——否则跑一半卡死或漏掉几个视频，你根本不知道。
为什么不用 Web 方式而选 PHP CLI 批量打水印
Web 请求有执行时间限制（
max_execution_time）、内存上限、请求中断风险，而一个 5 分钟的 4K 视频加水印可能耗时 90 秒以上，且需连续处理几十个文件。CLI 模式可绕过这些限制，适合后台定时任务或运维脚本。
- 用
php -f batch_watermark.php 启动，不受 Nginx/Apache 超时影响
- 可配合
nohup 或 systemd 长期运行，失败后也容易重试
- 避免上传/下载环节，直接操作服务器本地视频路径，IO 更快
- 不依赖用户交互，适合与日志系统、监控告警联动
PHP CLI 调用 ffmpeg 的安全拼接要点
直接拼接用户输入或未清理的路径进
shell_exec() 是高危操作，尤其当视频名含空格、括号、中文或单引号时，命令会截断或执行异常。
- 所有路径参数必须用
escapeshellarg() 包裹：escapeshellarg($inputPath)、escapeshellarg($watermarkPath)
- 禁止让用户控制
x=、y=、fontsize= 等滤镜表达式，只开放预设位置（如 "right-10,bottom-10"）并由 PHP 内部映射为合法 overlay 参数
- 中文文字水印必须指定 UTF-8 兼容字体，且
fontfile 路径不能含空格或中文——建议统一放在 /opt/fonts/NotoSansCJK-Regular.ttc 并提前验证可读
- 始终检查
ffmpeg 返回码：if ($returnCode !== 0) { error_log("ffmpeg failed: $output"); }
避免水印偏移的三个硬性条件
右下角水印跑飞、拉伸变形、贴到黑边里——这类问题在 CLI 批量中更难排查，因为没界面预览。
-
overlay 表达式里大小写不能错：W 和 H 是主视频宽高，w 和 h 是水印图尺寸；写成 x=w-w-10 就永远是 -10 像素，水印左出界
- 手机竖屏视频常带
rotate=90 元数据，FFmpeg 默认按存储像素贴图，导致坐标系旋转错位；必须加 -vf "transpose=2,setsar=1" 归一化（或先用 ffprobe 检测 rotation 并动态加 filter）
- 水印 PNG 必须含 Alpha 通道，且 ffmpeg 命令中要加
format=yuv420p，否则半透明区域发灰或全黑
批量循环中的资源与错误兜底
CLI 脚本不是跑一次就完事，它要扛住几十个视频连续处理，中间任何一个环节松懈都会让整个批次失效。
- 每个
exec() 后必须加 sleep(1)（尤其在低配 VPS 上），避免瞬间 fork 过多进程被系统 kill
- 用
set_time_limit(0) 解除脚本执行时间限制，但需手动控制单个 ffmpeg 超时：exec("timeout 300 ffmpeg -i ...", $output, $returnCode)
- 处理前用
is_file() + filesize() 校验源文件有效性，跳过 0 字节或损坏文件，记入日志而非中断
- 临时文件（如抽帧调试图）必须用
sys_get_temp_dir() 并在 finally 块中 unlink()，否则磁盘爆满
真正难的不是写出能跑通一条命令的代码，而是让脚本在凌晨三点自动处理 87 个视频时，第 42 个因磁盘满失败后，仍能继续跑完剩下 45 个，且每条错误都有明确路径和返回码可查——这要求你把“失败”当成默认状态来设计，而不是靠运气。
