【原创工具】Discuz! X3.5 存量附件批量转 WebP 脚本（游标续跑版）

IsaacZ

【原创工具】Discuz! X3.5 存量附件批量转 WebP 脚本（游标续跑版）


适用版本： Discuz! X3.5（含多表分表结构）
运行环境： PHP CLI + Imagick 扩展

---

一、为什么要做这个工具？

Discuz! X3.5 本身已经支持新上传附件自动转 WebP，但历史存量附件并不会自动转换。随着论坛运营多年，图片附件往往占据服务器绝大部分空间，而 WebP 在同等画质下通常能比 JPEG/PNG 节省 30%~60% 的磁盘空间。

本脚本专门解决以下痛点：

• 数万张历史图片手动转换不现实
• 网上现有脚本大多只支持单表，不兼容 X3.5 的 forum_attachment_0~9 分表结构
• 转换中断后无法续跑，每次都要从头再来
• 遇到坏文件/丢失文件直接 Fatal Error 终止，容错性差
• GIF 动图被强制转成静态 WebP，用户体验受损
  

---

二、核心功能一览

1. 全自动分表探测
脚本启动时会自动检测你的数据库结构：

• 自动识别 forum_attachment_0 ~ forum_attachment_9 哪些分表真实存在
• 同时处理 forum_attachment_unused 未使用附件表
• 兼容部分旧环境 forum_attachment 主表含完整字段的情况
  

无需手动改表名，开箱即用。

2. 智能 GIF 动图保护

• 通过 Imagick 精确探测帧数
• 多帧 GIF → 自动跳过，保留原动图，绝不强行转静态
• 单帧 GIF → 正常转换为 WebP，享受体积优化
  

3. 磁盘空间兜底保护（体积变大自动回退）
转换后如果发现 WebP 体积 大于等于 原图（某些已高度压缩的 JPEG 在质量 50 下反而膨胀），脚本会：

• 自动删除生成的 WebP
• 保留原图和数据库记录
• 游标推进，下次不再重复尝试
  

绝不为了转 WebP 而浪费空间。

4. 游标断点续跑（防死循环核心机制）
这是本脚本与市面上其他工具最大的区别：

• 采用 aid 游标推进 分页，而非传统 LIMIT OFFSET
• 每处理一条记录（无论成功、失败、跳过、丢失），游标实时写入 .webp_convert_cursor 文件
• 下次运行自动从断点续跑，已扫过的记录绝不回头
• 即使中途 Ctrl+C 强制终止、SSH 断开、服务器重启，也能无缝续跑
  

彻底告别「每次从头来」和「死循环卡在同一条坏记录上」。

5. 物理文件丢失的优雅处理
数据库里有记录，但磁盘上文件已丢失（搬家遗漏、手动误删等）：

• 保留数据库记录，帖子中显示缺图占位，不影响帖子结构
• 输出 [MISS] 日志，游标推进，下次自动跳过
• 不会导致脚本终止，也不会反复重试
  

6. 缩略图同步转换

• 自动读取后台缩略图设置（等比缩放 / 裁剪模式）
• 原缩略图 .thumb.jpg 自动清理
• 新生成 .webp.thumb.jpg（实际为 WebP 格式，兼容 Discuz 命名习惯）
• 数据库 thumb 字段自动更新
  

7. 冲突脏数据自动清理
如果之前运行过其他转换脚本，可能留下：

• 0 字节的空 .webp 文件
• 异常小的损坏 .webp 文件
  

脚本会自动检测并清理这些脏数据，然后重新生成正确的 WebP。

8. 严格的 Imagick 统一转换

• 去除 GD 降级逻辑，强制依赖 Imagick
• 确保所有图片（无论 JPG/PNG/GIF/BMP）转换效果一致
• 压缩质量统一为 50（与 Discuz! X3.5 新上传 WebP 的水印/压缩策略对齐）
  

---

三、命令行用法

将脚本放到论坛根目录（与 config/config_global.php 同级），SSH 进入后执行：

1. # 进入论坛根目录
   
2. cd /www/wwwroot/yourdomain.com
   
3. 
   
4. # 总共扫描 500 条记录后自动停止（无论成功/失败/跳过都算）
   
5. php convert_attachments_to_webp.php 500
   
6. 
   
7. # 不限数量，全部跑完
   
8. php convert_attachments_to_webp.php 0
   
9. 
   
10. # 从 aid < 100000 的位置开始倒序处理（配合游标一般不需要手动指定）
    
11. php convert_attachments_to_webp.php 500 100000
    

复制代码

运行日志示例

1. ===== 正在处理表: pre_forum_attachment_0 =====
   
2. 待处理记录数: 4845
   
3. [OK] aid=173402 | 202511/04/...jpg -> ...webp | 节省 45.2 KB
   
4. [MISS] aid=173350 | 物理文件已丢失，保留占位: ...
   
5. [SKIP] aid=173299 | 已是WebP/GIF动图
   
6. [CLEAN] aid=161368 | 清理冲突脏数据: ...
   
7. [ERR] aid=161619 | ... | Imagick 转换失败: unable to open file ...
   
8. --- 本批完成 ---
   

复制代码

续跑机制

• 正常中断（达到上限、全部完成）→ 自动保存游标
• 异常中断（SSH 断开、Fatal Error 前）→ 最后一条处理的游标已实时写入
• 下次直接执行同样的命令即可续跑
  

强制从头开始：

1. rm .webp_convert_cursor && php convert_attachments_to_webp.php 500
   

复制代码

---

四、注意事项 & 环境要求

项目	要求
PHP 版本	7.4+（推荐 8.0+）
运行模式	必须 CLI（命令行），不支持 Web 访问
扩展依赖	Imagick（必须安装，不再支持 GD 降级）
权限	需要对 data/attachment/forum/ 有读写权限
备份	首次运行前建议备份数据库 + 附件目录，虽然脚本经过大量测试，但数据无价

不适合转换的情况（脚本会自动跳过）

• 多帧 GIF 动图
• 已经是 WebP 格式的附件
• 转换后体积变大的图片（回退保护）
• 物理文件丢失的记录（保留占位）
  

---

五、技术实现亮点（给开发者参考）

• 游标分页替代 OFFSET 分页
  ORDER BY aid DESC + aid < $lastAid 确保已处理记录永不回头，时间复杂度 O(1)。
• 实时持久化游标
  每条记录处理完立即 file_put_contents，即使进程被 kill -9，最多损失一条记录。
• 单条失败隔离
  任何单张图片转换失败（Imagick 内部错误、磁盘满、文件损坏）只会影响自身，不会终止整个批次。
• 零侵入
  不修改 Discuz! 核心文件，不新增数据表，纯独立脚本，随时可删。
  

---

六、下载 & 反馈

下载地址： convert_attachments_to_webp.rar (4.39 KB, 下载次数: 0, 售价: 30 金钱)

2026-8-3 20:16 上传

点击文件名下载附件
阅读权限: 20

使用反馈： 如有问题请直接回复本帖，建议附上：

• 具体的 [ERR] 或 [FATAL] 报错信息
• 运行命令（含参数）
• PHP 版本和 Imagick 版本（php -v 和 php -m | grep imagick）
  

---

更新记录：

• v1.0 初始版本，支持分表探测、GIF 动图保护、游标续跑
• v1.1 增加体积变大回退保护，优化丢失文件处理策略
• v1.2 统一 Imagick 强制依赖，去除 GD 降级，压缩质量对齐 X3.5 默认值 50
  

---

七、使用效果







批量转换前的空间占用：



批量转换后省了好几个G：



祝各位站长磁盘空间越来越宽裕！🎉

---

后续还需要进行缓存修复操作：[2026-08-03] [修复] [WebP缓存修复] - 全站转WebP后关注流/广播页旧图404修复

浅斟低唱

看起来 很厉害的样子！！！
站长大才！！！！