上传图片转 WebP 插件

自动将后台/前台上传的 JPG / PNG / GIF / BMP 图片转换为 WebP 格式，保持像素尺寸不变，在视觉无损前提下大幅减小文件体积，节省存储空间与 CDN 流量。

功能特性

三级降级压缩：cwebp（Google 官方）> Imagick 扩展 > GD 库，自动探测并选择最优工具

透明通道保留：PNG / GIF 透明背景转 WebP 后仍保留透明，不会变黑

安全兜底：转换失败、体积未减小、工具缺失时，自动回退保留原文件，不影响上传流程

只保留更小结果：压缩后体积 ≥ 原图时，自动删除 WebP 并保留原文件

不修改尺寸：仅转换格式和压缩质量，不缩放分辨率

hook 挂载：监听 upload_file_save_after 系统钩子，分片合并成功后才开始转换，不影响上传进度条

环境要求

项目 要求

ThinkCMF 版本 X 系列（支持 upload_file_save_after 钩子）

PHP 版本 7.4+ / 8.x（推荐 8.2）

PHP 扩展 ext-zip（打包用），GD 或 Imagick 至少其一，最好装 cwebp

可选优化 安装 webp 系统包（cwebp 命令行工具，压缩率最高）

cwebp 安装（推荐，压缩质量和体积最佳）

Bash

1

2

3

4

5

6

7

8

9

10

11

# Debian / Ubuntu

sudo apt-get install webp

# CentOS / RHEL

sudo yum install libwebp-tools

# macOS (Homebrew)

brew install webp

# Windows：下载 https://developers.google.com/speed/webp/download

# 解压后把 cwebp.exe 放到 C:\webp\cwebp.exe 或 PATH 任意目录

安装方法

方式一：后台插件管理安装（推荐）

登录后台 → 插件管理 → 上传安装插件

选择 plugin_upload_image_to_webp_xxxxxx.zip 包上传

安装成功后，在插件列表点「启用」

方式二：命令行直接打包分发

Bash

1

2

3

# 在已开发好的项目根目录执行

php think publish:plugin UploadImageToWebp

# 输出：D:\www\ThinkCMF/data/publish/plugin_upload_image_to_webp_YYYYMMDD_HHMMSS.zip

方式三：手动部署

将 upload_image_to_webp 目录拷贝到目标项目 public/plugins/ 下

登录后台 → 插件管理，扫描新插件后安装并启用

安装流程会自动：

在 cmf_hook 表注册 upload_file_save_after 系统钩子（如不存在）

在 cmf_hook_plugin 表挂载插件到钩子

清钩子缓存，立即生效

配置说明

插件后台 → 设置 页可配置以下参数：

配置项 类型 默认值 说明

启用转换 开关 开启 关闭后所有上传图片保持原格式

压缩质量 数字 85 WebP 质量 0-100，见下方质量对照表

小于多少不压缩(KB) 数字 700 小于该大小的图片跳过转换（小图收益低），设为 0 表示不限制

质量对照表

场景 推荐质量 效果

截图 / 后台表单截图 / 含文字海报 80-85 文字边缘锐利，无模糊感

产品照片 / 风景图（无文字） 70-75 视觉无损，体积甜点区

用户头像 / 小缩略图 60-65 体积最小，可见损失可接受

追求近乎无损 85-90 体积稍大，最高保真

极致压缩，能接受画质损失 50-60 体积缩减最大

使用流程

进入插件设置 → 先看「环境检测」是否打勾 ✔，最好三个工具至少有一个可用

调整「压缩质量」和「小于多少不压缩」两个参数，保存

正常上传图片即可，插件自动处理，无需人工介入

转换后的效果

上传入口：不区分，所有 file_type=image 的走钩子都会触发（文章配图、幻灯片、用户头像、自定义上传）

文件路径：新 .webp 与原文件同目录、同名换后缀；原文件自动删除（有收益时）

数据库：cmf_upload_file 表的 file_path、md5、sha1 自动为 WebP 新文件

云存储：如果项目配了云存储钩子，上传到云端的就是压缩后的 WebP 文件

目录结构

Plain Text

1

2

3

4

5

6

upload_image_to_webp/

├── UploadImageToWebpPlugin.php   # 主入口类（钩子处理、安装、卸载）

├── config.php                    # 插件配置表单 + 环境检测

├── lib/

│   └── WebpCompressor.php        # WebP 压缩核心类（cwebp / Imagick / GD 三级降级）

└── README.md                     # 本说明

常见问题

Q: 为什么有些图片没转？

图片已经是 .webp 后缀 → 直接跳过，避免重复压缩

体积小于「小于多少不压缩」阈值 → 小图转了反而可能变大

转换后体积比原图还大 → 自动保留原文件，删除 WebP

Q: 后台设置里环境检测三个都是 ✘？

无任何可用工具时插件会静默跳过不压缩，不报错。建议装 cwebp 或启用 GD/Imagick

Q: 转换后背景变黑？

GD 库对 PNG 透明支持有限，升级为 Imagick 或 cwebp 可完美保留

Q: 卸载插件会删除已上传的 WebP 图片吗？

不会。卸载仅解除钩子挂载和清缓存，不碰任何上传文件

版本历史

版本 日期 变更

1.0.0 - 初始版本：三级降级压缩、透明通道保留、大小阈值过滤

1.0.1 2026-08-19 移除「大于多少不压缩(KB)」配置，超大图也尝试转换

评论