WordPress基于GD引擎编程实现全尺寸图片转WebP 纯代码无插件
WordPress 基于GD库的极简WebP转换实现
最优触发钩子选择
- 选用
wp_generate_attachment_metadata钩子,设置优先级10,传入完整3个参数- 触发时机为WordPress完成原图、所有自定义尺寸缩略图全部生成并写入磁盘之后,所有待转换文件的路径、文件名完全确定,不会出现漏转、文件不存在的问题
- 相比
wp_update_attachment_metadata钩子,该节点在元数据写入数据库之前触发,就算转换逻辑出现异常,也不会破坏原有媒体库的元数据存储,不会影响原有图片的正常调用 - 完全不需要引入额外的定时任务逻辑,转换流程和上传、重新生成缩略图流程绑定,无额外队列开销
- 所有WebP文件仅作为独立静态文件存储,不将WebP相关元数据写入WordPress数据库,媒体库始终仅保留原图及对应格式的元数据,完全匹配前端
<picture>标签的调用逻辑
钩子变量调试方法
之前调试无输出的核心原因是WordPress后台上传请求的输出会被接口层拦截,普通ob打印、控制台输出的内容不会在前端展示。
正确的调试实现方式:
- 钩子回调中直接用PHP原生错误日志方法写入变量结构,无需依赖额外调试工具
- 日志默认写入WordPress站点的
wp-content/debug.log,符合系统默认调试逻辑,直接打开文件即可查看完整变量结构
调试代码示例:
add_filter('wp_generate_attachment_metadata', 'debug_attachment_vars', 10, 3); function debug_attachment_vars($metadata, $attachment_id, $context) { // 写入完整变量结构到日志 error_log("=== 附件ID: {$attachment_id} ===" . PHP_EOL); error_log("触发上下文: " . print_r($context, true) . PHP_EOL); error_log("元数据结构: " . print_r($metadata, true) . PHP_EOL); // 原样返回元数据,不破坏原有上传流程 return $metadata; }
开启日志的前置操作:在
wp-config.php中添加define('WP_DEBUG', true); define('WP_DEBUG_LOG', true);,所有通过error_log输出的内容会自动写入指定日志文件
实际可直接使用的变量结构说明,无需反复调试:
$attachment_id:整数类型,当前上传/更新附件的对应文章ID$metadata:数组结构,根节点file字段存储原图相对于uploads目录的相对路径;根节点sizes子数组存储所有已生成的中间尺寸文件信息,每个子项包含文件路径、宽高、mime类型字段$context:字符串类型,标识钩子触发来源,新上传图片时为create,手动触发重新生成缩略图时为update
完整可运行转换逻辑
实现逻辑前置校验:
- 首先判断当前PHP环境是否开启GD库的WebP编码支持(即
imagewebp方法是否存在),不支持时直接终止流程,不影响正常图片上传 - 转换质量统一设置为82,兼顾文件体积和显示画质,可根据需求调整
- 仅处理jpeg、png两种常见源格式,其他格式自动跳过
- 遍历范围覆盖原图 + 所有自定义尺寸文件,逐一生成同目录下的WebP版本
完整代码:
/** * GD库实现极简WebP转换,无冗余功能 */ add_filter('wp_generate_attachment_metadata', 'gd_convert_to_webp', 10, 3); function gd_convert_to_webp($metadata, $attachment_id, $context) { // 环境校验:不支持WebP编码直接返回,不破坏原有流程 if (!function_exists('imagewebp')) { return $metadata; } // 获取uploads目录的绝对路径 $upload_dir = wp_get_upload_dir(); $base_dir = trailingslashit($upload_dir['basedir']); // 处理原图 $original_file_path = $base_dir . $metadata['file']; convert_single_image_to_webp($original_file_path); // 处理所有中间自定义尺寸的文件 if (!empty($metadata['sizes'])) { // 提取原图所在目录,所有中间尺寸文件和原图存放路径一致 $file_dir = trailingslashit(dirname($original_file_path)); foreach ($metadata['sizes'] as $size_info) { $size_file_path = $file_dir . $size_info['file']; convert_single_image_to_webp($size_file_path); } } // 原样返回元数据,不写入任何WebP相关信息 return $metadata; } /** * 单文件转WebP的通用处理方法 */ function convert_single_image_to_webp($source_path) { // 源文件不存在时直接跳过 if (!file_exists($source_path)) { return; } // 生成同路径下的WebP文件路径 $webp_path = preg_replace('/\.(jpe?g|png)$/i', '.webp', $source_path); // 已存在同路径的WebP文件时直接跳过,避免重复转换 if (file_exists($webp_path)) { return; } // 读取源文件格式,仅处理支持的图片类型 $mime = mime_content_type($source_path); switch ($mime) { case 'image/jpeg': $image = imagecreatefromjpeg($source_path); break; case 'image/png': $image = imagecreatefrompng($source_path); // 保留PNG透明通道 imagepalettetotruecolor($image); imagealphablending($image, true); imagesavealpha($image, true); break; default: // 非支持格式直接跳过 return; } // 图像资源创建失败时直接终止 if (!$image) { return; } // 输出WebP文件 imagewebp($image, $webp_path, 82); // 销毁内存中的图像资源,避免大文件处理时出现内存溢出 imagedestroy($image); }
适配说明
- 完全匹配已配置的自定义图片尺寸规则:逻辑遍历元数据中所有已生成的尺寸文件,后续新增任何自定义尺寸都不需要修改转换代码
- 所有生成的WebP文件和源文件完全同目录,文件名为
原文件名.webp,和前端<picture>标签的srcset规则完全匹配,不需要额外的路径替换、路由规则 - 无冗余功能:不实现文件分发、自定义存储路径、数据库写入、.htaccess规则等非必要功能
- 兼容老图片:在媒体库手动触发重新生成缩略图时,会自动为所有尺寸的图片生成对应WebP版本
- 已做重复转换校验:如果目标路径已存在WebP文件,不会重复写入,避免不必要的资源消耗
内容的提问来源于stack exchange,提问作者lowtechsun
相关产品推荐
相关产品推荐

