You need to enable JavaScript to run this app. WordPress基于GD引擎编程实现全尺寸图片转WebP 纯代码无插件
优惠活动
大模型
产品
解决方案
定价
更多

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

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.10.24 09:54:04