本文目录导读：
Thumbnailator 是一个非常流行的 Java 图片处理库，专门用于图片压缩、缩放、裁剪和水印等操作。
它的核心优势在于：API 设计极其简洁（使用流畅的 Builder 模式），通常只需一行代码即可完成复杂的图片处理，且底层基于 Java 的 ImageIO，不需要依赖第三方图像处理引擎（如 OpenCV 或 ImageMagick）。
核心依赖（Maven/Gradle）
Maven
<dependency>
<groupId>net.coobird</groupId>
<artifactId>thumbnailator</artifactId>
<version>0.4.20</version> <!-- 建议使用最新版，截至2025年为0.4.20 -->
</dependency>
Gradle
implementation 'net.coobird:thumbnailator:0.4.20'
常用压缩与缩放 API
1 最简单的压缩（按比例缩放）
import net.coobird.thumbnailator.Thumbnails;
// 将原图按比例压缩为宽度200像素（高度自动等比缩放）
Thumbnails.of("input.jpg")
.width(200)
.toFile("output.jpg");
2 指定宽高（强制拉伸/裁剪）
// 强制缩放到200x200，不保持比例（可能导致变形）
Thumbnails.of("input.jpg")
.size(200, 200)
.keepAspectRatio(false)
.toFile("output.jpg");
3 高质量压缩（控制输出质量）
Thumbnails.of("input.jpg")
.size(800, 600)
.outputQuality(0.8) // 0.0 ~ 1.0，0.8表示80%质量
.outputFormat("jpg") // 指定输出格式
.toFile("output_compressed.jpg");
4 按比例缩放 (scale)
// 缩放为原来的一半
Thumbnails.of("input.jpg")
.scale(0.5)
.toFile("output.jpg");
// 放大2倍
Thumbnails.of("input.jpg")
.scale(2.0)
.toFile("output.jpg");
批量处理目录下的所有图片
// 将 inputDir 下所有图片转为 200x200 并输出到 outputDir
Thumbnails.of(new File("inputDir").listFiles())
.size(200, 200)
.outputFormat("jpg")
.toFiles(new File("outputDir"), Rename.PREFIX_DOT_THUMBNAIL);
// 或使用 .toFiles(new File("outputDir"), (name) -> "thumb_" + name);
带水印、裁剪、旋转的高级用法
1 添加水印
import net.coobird.thumbnailator.geometry.Positions;
Thumbnails.of("input.jpg")
.size(800, 600)
.watermark(Positions.BOTTOM_RIGHT, // 水印位置：右下角
ImageIO.read(new File("watermark.png")),
0.5f) // 水印透明度 0.5
.toFile("output_with_watermark.jpg");
2 裁剪 (sourceRegion)
// 从原图中心裁剪300x300区域
Thumbnails.of("input.jpg")
.sourceRegion(Positions.CENTER, 300, 300)
.size(200, 200)
.toFile("cropped.jpg");
3 旋转
// 旋转90度
Thumbnails.of("input.jpg")
.size(800, 600)
.rotate(90) // 90, 180, 270
.toFile("rotated.jpg");
内存中处理（BufferedImage）
适合网络请求、上传等不需要写入磁盘的场景：
// 输入：BufferedImage
BufferedImage original = ImageIO.read(new File("input.jpg"));
// 处理并返回 BufferedImage
BufferedImage compressed = Thumbnails.of(original)
.size(400, 300)
.outputQuality(0.7)
.asBufferedImage();
// 直接写入输出流 (Response)
Thumbnails.of(original)
.size(400, 300)
.outputFormat("jpg")
.toOutputStream(response.getOutputStream());
性能优化建议
| 场景 | 建议 |
|---|---|
| 大图压缩 (>10MB) | 先用 scale(0.5) 缩小，再用 outputQuality(0.8) |
| 批量处理 | 使用 asBufferedImages() 批量加载到内存再处理 |
| 高并发服务器 | 将 Thumbnailator 对象设计为单例（线程安全） |
| 避免失真 | 尽量使用 width() 或 height() 单边缩放，不要强制双边界定 |
常见问题
Q1: 压缩后图片反而变大了？
- 原因：输出格式/质量设置不合理，PNG 转 JPG 且质量设置很高。
- 解决：设置
outputQuality(0.6~0.8)，且确认输出格式为 JPEG。
Q2: 图片出现锯齿或模糊？
- 解决：启用高质量缩放算法：
.useExifOrientation(true) // 保持EXIF方向 .outputQuality(0.85)
Q3: 不支持某些格式（WebP、HEIC）？
- Thumbnailator 底层依赖 Java 的 ImageIO，默认只支持 JPG/PNG/GIF/BMP。
- 若需 WebP 支持，可集成
webp-imageio包。
完整实用示例（封装工具类）
public class ImageCompressor {
public static void compress(File source, File target, int width, int height, float quality) throws IOException {
Thumbnails.of(source)
.size(width, height)
.outputQuality(quality)
.outputFormat("jpg")
.toFile(target);
}
public static void compressToStream(InputStream inputStream, OutputStream outputStream, int width, int height) throws IOException {
Thumbnails.of(inputStream)
.size(width, height)
.outputFormat("jpg")
.toOutputStream(outputStream);
}
}
| 特性 | Thumbnailator |
|---|---|
| API 简洁性 | ⭐⭐⭐⭐⭐（一行搞定） |
| 性能 | ⭐⭐⭐⭐（中等规模图片极快） |
| 功能完整度 | ⭐⭐⭐⭐（缩放/裁剪/水印/旋转） |
| 不支持格式 | WebP / HEIC（需额外插件） |
| 适用场景 | Java Web 图片上传压缩、缩略图生成 |
如果你需要 更高性能的批量处理 或 视频缩略图，可以考虑转向 FFmpeg + Java 封装，但针对纯图片压缩场景，Thumbnailator 是目前 Java 生态中最推荐的工具之一。
