对现有媒体库执行批量处理

这次运行做什么——以及事先必须打开什么

Kakapo Performance 的两个图片模块在 WordPress 生成图片尺寸的那一刻开始工作：压缩模块设定质量并从生成的尺寸中移除 EXIF、IPTC 和 XMP 标记，格式模块则创建 WebP 和 AVIF 衍生文件。因此两者都从下一次上传开始生效。对于已经躺在媒体库里的图片，什么也不会发生——而批量运行补的正是这个缺口。

这次运行不会自作主张。它对现有文件所做的，正是您在上方为新上传启用的设置：WebP 和/或 AVIF，以及“移除元数据”。如果这些都没有启用，开始按钮就会被锁定并说明原因——例如服务器无法写入 WebP，或者干脆没有任何设置处于启用状态。卡片“对现有媒体库进行后处理”位于“图片”区域、图片设置的下方；界面上的顺序就是操作的顺序：先设置，再让它跑一遍现有文件。

被处理的只有 JPEG 和 PNG 类型、且不在回收站中的附件。“库存中的 JPEG/PNG 图片”这一行会在你开始之前告诉你数量。

开始、旁观、暂停

点击“开始批量运行”会创建这次运行并立即开始。工作分轮次进行，每轮的时间预算为 8 秒；随后该轮回报结果，显示随之更新，下一轮在 200 毫秒后启动。如果一轮结束时剩余时间不足 3.5 秒，就不会再开始处理下一个附件——格式模块内部按每张图片至少三秒来计算。在设置了 max_execution_time 的服务器上，预算还会被额外限制在该上限的 80%，以免这一轮在请求中途被切断。

进度条显示的是真实进度：已完成的附件数除以总数。下面是实时数字——生成和跳过的衍生文件，WebP 和 AVIF 各占一行，此外还有被瘦身的文件和释放出来的字节数。最下面滚动显示最近 14 行日志，每行都带着文件名以及这个文件的处理结果。

“暂停”会停止这次运行。按钮随后叫作“继续”，下一次开始时会正好从它停下的那个附件接着往下做。你直接把标签页关掉也是同样的结果：运行停下来，什么都不会丢。当你重新打开这个页面时，它会查询状态，并自动把尚未完成的运行继续推进。

运行如何挺过一次中断

进度是在处理每一个附件之前就保存的，而不是处理之后才保存。如果某一轮中途夭折——Web 服务器的执行上限、内存、某个让 GD 噎住的文件——那么下一轮就知道卡在了哪里。如果同一个附件连续三次尝试都毫无进展，它会被跳过，并在日志里留下一行明文说明，而不是让整次运行永远卡在一个文件上。

同时打开的两个管理页面不会互相绊住：一把锁始终只允许一轮运行。如果某一轮被 Web 服务器强行终止而锁留在了那里，那么 180 秒之后它就算作无主的，会被接管。

继续时总数会重新计算，而不是被冻结——在暂停和继续之间可能上传或删除过东西。如果你在运行途中把所有图片设置都关掉，它会自己停下来，而不是去做已经没人要求的工作。“重置”会丢弃进度和报告；已经生成的文件仍然留着。

正确读懂报告

最后是一行结尾统计，写着实测的文件大小——不是估算。对每一个生成的衍生文件，运行都会把源文件的大小与结果的大小做对比，两者都是生成那一刻的真实数值。只统计本次运行中新产生的内容；上传时就已经转换过的，不会再出现一次。

有三处是有意这样写、而不是写得更好看：WebP 和 AVIF 各占一行，因为同一个源文件会派生出两个衍生文件——合成一个总数就会把源文件算两遍。因此百分比只在各自那一行内有效，不能相加；浏览器每次只会取这两种格式中的一种。还有，新文件会在硬盘上额外占用空间：省下来的是传输给访客的那部分。真正释放存储空间的只有移除元数据，而这些字节写在单独的一行里。

如果什么也没生成，报告同样会这么说：要么这批文件此前就已经全部处理完毕，要么没有任何结果比它的源文件更小。不比源文件小的结果会被丢弃，并计为“已跳过”——绝不会算成收益。

当有内容被跳过时

每一个没有生成的衍生文件都会得到一条明文原因，这些原因会汇总写在结尾那一行里：

• “不小于原图”——正常情况，保留原图。• “超出可用内存”——格式模块会在解码前检查图片尺寸并直接拒绝，而不是让 PHP 撞上内存上限。• “目标位置已存在文件”——它不会被覆盖。这通常发生在附件上的记录丢失、而文件还在的情况下。• “无法读取”——文件损坏、CMYK-JPEG 或某种少见的变体。• “无法写入”——请检查 uploads 目录的权限。• “此服务器上没有该格式”——AVIF 需要 PHP 8.1 或更新版本并带 libavif，WebP 需要带 libwebp 的 GD 库。

有两件事常被当成故障，其实并不是：第二次运行几乎看不到什么动静，因为已完成的工作不会重做——附件上的一个标记记录着已经为多少个文件清除过元数据。还有，改动质量等级并不会更新已经生成的文件；要做到那一点，得先把衍生文件删掉。