Rhex 图片自动压缩插件：在图片进入本地或对象存储之前，自动压缩、缩放或转换格式，同时继续复用 Rhex 原有的 MIME 校验、哈希去重、上传配额、上传记录和 local / S3 / OSS 存储流程。
- 后台启用或停用自动压缩
- 仅调整编码质量，或限制尺寸并调整质量
- 保持原格式，或统一转换为 JPEG / WebP / AVIF
- 设置质量、最大宽度、最大高度和最小处理体积
- 可选择仅在处理结果更小时采用新图片
- 可设置 JPEG 透明区域填充颜色
- 可按正文、评论、封面、私信、图片附件、头像和后台素材选择应用范围
- GIF、SVG、动画 WebP / AVIF 默认跳过
- 单张图片处理失败时回退原图，不中断整个上传请求
当前插件不能直接运行在未经修改的 Rhex 1.1.0 官方镜像中。
插件依赖 upload provider 的 transformFile() hook。该扩展允许插件在 Rhex 水印之后、去重与存储之前修改图片 Buffer：
上传格式与原始大小校验
-> Rhex 水印
-> 插件压缩、缩放或转码
-> 宿主重新检测 MIME、文件大小和 SHA-256
-> 去重与上传配额
-> local / S3 / OSS 保存
相关上游 PR：
- lovedevpanda/Rhex#23：修复 PostgreSQL advisory lock 参数类型导致的上传 500
- lovedevpanda/Rhex#24：补齐生产镜像所需的
cross-env/tsx - lovedevpanda/Rhex#25：增加插件直接依赖的
transformFile()hook
其中 PR #25 是本插件的直接宿主依赖；PR #23 与 PR #24 是开发及生产部署期间发现的上传和镜像配套修复。
在 PR #25 进入正式版本和官方镜像之前，可以使用 Jiosanity/Rhex 中包含该扩展的构建，或将 docs/rhex-upload-transform.patch 应用到对应的 Rhex 基线源码后自行构建。
- 部署包含
transformFile()扩展的 Rhex 宿主。 - 按照 Rhex 插件文档启用可信插件代码执行环境。
- 从 Releases 下载
image-compressor-1.0.3.zip。 - 进入 Rhex 后台“插件管理”，上传 ZIP 并启用。
- 打开插件详情页，设置压缩方式、质量、尺寸和应用范围。
建议首次使用以下配置：
- 输出格式：保持原格式
- 质量：82
- 最大尺寸：2560×2560
- 最小处理体积：200 KB
- 仅在结果更小时采用处理后的图片
如果统一输出为 WebP 或 AVIF，需要同时在 Rhex 后台允许上传类型中加入对应扩展名。
仓库中的 addon.json、dist/、assets/ 和 README.md 是插件安装包所需内容。在仓库根目录执行：
zip -X -r image-compressor-1.0.3.zip addon.json dist assets README.md安装包中的 addon.json 必须位于 ZIP 根目录，不能额外套一层文件夹。
插件不需要单独安装 npm 依赖。可以使用 Node.js 检查所有 JavaScript 模块语法：
find dist assets -type f \( -name '*.mjs' -o -name '*.js' \) -print0 \
| xargs -0 -n1 node --check更完整的验证结果见 docs/verification.md。
addon.json 插件清单
dist/server.mjs 服务端入口与 provider 注册
dist/config.mjs 后台设置读取与归一化
dist/image-compressor.mjs Sharp 图片处理逻辑
dist/admin.mjs 后台页面与 API 注册
assets/ 后台设置页面资源
docs/ 宿主临时补丁与验证记录
- 图片处理在 Web/API 进程内同步执行，大图或高并发环境应关注 CPU 和接口耗时。
- 插件服务端代码按照 Rhex 的可信代码模型运行，请只安装可信来源的插件包。
- 升级 Rhex 前请检查官方版本是否已经原生提供
transformFile()，避免重复应用补丁。 - 使用修改版宿主或第三方镜像前，请先备份数据库、上传目录和插件目录。
MIT License © 2026 xiaoten