简介：在Java开发中处理图片格式时，HEIC压缩率高但兼容性差，直接读取或上传常会遇到阻碍。这份面向Java开发者的HEIC转PNG/JPEG示例资源，基于HEIC-Convert-Java项目演示如何借助ImageMagick完成格式转换，并提供代码封装思路，帮助解决苹果设备图片在旧系统或业务链中无法使用的问题。压缩包共7个文件、约22.19MB，包含Java源码、im4java-1.4.0.jar依赖、Flower.HEIC与Flower.PNG样例、ImageMagick安装与convert配置截图、README说明等，按目录组织，便于对照学习。已有4125人学习。从源码和截图中，读者可以快速搭建本地转换环境，理解Runtime执行外部命令的关键步骤，掌握转换成功与否的退出码判断，并进一步了解批量转换、服务化封装以及libheif、jheif等纯Java替代库的选型思路，为兼容HEIC设备与应用的开发提供实用参考。 前阵子做网盘图片处理服务，接到了一个听起来简单、做起来却让人血压升高的需求——把用户上传的 HEIC 图片转成 JPEG 和 PNG，好让网页端和安卓端能正常预览。当时我第一反应是“不就一个格式转换吗”，结果真开工才发现，Java 生态里处理 HEIC 的配套远没有 JPEG、PNG 那么成熟。网上资料东一榔头西一棒子，官方库要么毛坯得不行，要么文档看得人一头雾水。趁着这个项目收尾，我把这次调研、选型、编码和踩坑的全过程整理出来，希望能帮到正在被 HEIC 折腾的 Java 开发者。
先说清楚这个项目的核心输出：在 Java 服务端接收 HEIC 格式的图片文件，通过合理的技术方案将其解码并转码为 PNG 或 JPEG，最终能直接存 OSS、转存云存储或交给前端展示。整个过程不需要用户安装任何插件，也不需要客户端做额外处理，所有转换逻辑收敛在后端。我不只是给代码，还会把底层的格式差异和选型逻辑讲明白。
1. 为什么 Java 处理 HEIC 这么麻烦
1.1 HEIC 到底是什么，和 HEIF 是什么关系
HEIC 全称 High Efficiency Image Coding，是苹果公司在 iOS 11 之后主推的照片默认格式。它实际是基于 HEIF（High Efficiency Image File Format）容器的一款具体实现，内部视频编码层走的是 HEVC/H.265。你可以把 HEIF 理解成一个大盒子，里面可以装不同编码格式的图像数据，而 HEIC 是这个盒子的特定用法，专门承载 HEVC 编码的图像数据。JPEG 则完全不同，它直接把压缩数据写进文件头尾，不搞这么复杂的容器层级。
这个差异带来两个直接结果：一是 HEIC 比同等画质的 JPEG 体积小很多，一般能省 40% 到 50% 的空间，对于动不动就是 1200 万像素起步的 iPhone 照片来说，省出的空间非常可观；二是由于 HEVC 编码本身的复杂度，解码 HEIC 比解码 JPEG 需要的计算资源高得多，不光是循环解压那么简单，还有帧内预测、整数变换、去块滤波等一系列计算环节。
理论上苹果当初推 HEIC 是瞄准下一代图片格式去的，但现实是 Windows 和安卓生态跟进得慢半拍。这就导致 Java 后端经常收进来 iPhone 用户上传的 .heic 文件，但下游的图片服务、CDN、老旧的业务系统根本不认识它。网上甚至有用户把 HEIC 改后缀为 JPG 再上传，结果后端直接报错抛异常，这种场景在我的工单里出现过不止一次。
1.2 Java 原生 ImageIO 的边界在哪里
Java 自带ImageIO类可以读 JPEG、PNG、BMP、GIF、WBMP，部分 JDK 还支持 TIFF，但唯独对 HEIC 没有任何内置支持。原因很简单，HEVC 编码涉及大量专利相关的东西，OpenJDK 的默认发行版不可能把它内置进去，否则光授权费用就够喝一壶的。这就意味着我们不能像读 PNG 那样，ImageIO.read(new File(...))一把梭。
你可能想问，能不能直接把 HEIC 的二进制数据塞进BufferedImage？答案是基本无解。HEIC 文件内部是 ISO-BMFF 结构，如果不经过完整解码流程，直接读字节流拿不到像素矩阵。换句话说，Java 要处理 HEIC，底层必须有一个真正的 HEVC 解码器在做支撑，这一关绕不开。
所以在项目设计之初，我给自己定了一条准则：不追求“纯 Java 手写解码器”，而是找一个可靠、可维护、性能过得去的解码桥接方案。纯手写 HEVC 解码器在工业场景下不现实，那是 FFmpeg 和 libde265 这种 C/C++ 库十几年积累的成果，Java 里再造一个轮子既不经济，也不安全。
2. 技术选型解析——绕不开的跨语言桥接
2.1 市面上几类方案的横向对比
现在 Java 领域处理 HEIC 的方案，归纳起来就四条路：
第一类，JNI 直接调用 C/C++ 库。典型代表是开源库 libheif，它底层绑定 libde265 或 x265 来做 HEVC 编解码。JNI 封装之后 Java 可以调用 C 接口，性能和可控性都最好，但编译成本很高，你需要为不同平台分别构建动态链接库，Windows 一套、Linux 一套、macOS 又是一套，而且 JNI 代码写起来繁琐，还得处理内存引用防止崩溃。
第二类，通过进程调用外部命令行工具。比如装好 ImageMagick、FFmpeg 或者 libheif 自带的 heif-convert 命令，Java 用ProcessBuilder启动子进程完成转换。这种方案实现最简单，几行代码就能跑通，但对服务器环境有强依赖，部署新机器时必须额外安装系统依赖，而且每张图片都要拉起一个新进程，性能捉襟见肘。
第三类，纯 Java 实现的解码方案。确实有一些早期项目尝试把 HEIF 的容器解析用纯 Java 做，再结合一些硬编码方式解码。但我实际测试下来，要么只支持特定规格的 HEVC，要么遇到苹果设备拍摄的高分辨率照片就解码失败，可用度很低。我把这一类定位为“原理学习可以，生产使用风险大”。
第四类是搜 GitHub 时偶然发现的 heif-converter 这个开源库。它本质上还是通过 JNI 的方式，但不像第一类那样要自己编译 JNI 代码，而是把预编译好的 libheif 动态库打进了 Jar 包里，然后在运行时自动解压加载。它对使用者隐藏了所有跨语言细节，API 设计得非常简单，核心就一个HeifConverter类。我当时测试完就直接定了这个方案，因为它在“集成便捷性”和“解码能力”之间找到了很好的平衡。
2.2 为什么选 heif-converter 而不是 FFmpeg
老实说，FFmpeg 能力极强，不光能转 HEIC，视频、音频、各种封装格式都能处理。但我最后没选它，原因是它在服务端的部署太“重”了。FFmpeg 的二进制包动辄几十上百 MB，还带一堆依赖库，在瘦身过的 Docker 镜像里塞这么个大家伙，不仅镜像体积翻倍，每次部署都要担心基础库缺失。另外，FFmpeg 的命令行参数虽然灵活，但在高并发场景下，每张图片都 fork 一个子进程，资源的消耗让我心疼。
heif-converter 就不一样，它只在 JVM 进程内做 JNI 调用，没有进程切换、没有命令行解析，卡车司机还是那个卡车司机，但你是把货直接搬上车，而不是每次都把卡车重新组装一遍。实测下来，用 heif-converter 转换一张 1200 万像素的 HEIC 照片到 JPEG，耗时大约 200 到 400 毫秒，取决于是不是第一次加载动态库。这个性能对我来说完全够用。
还有一点就是它天然适配 Spring Boot 的打包方式。你要知道，Java 服务打成 Fat Jar 之后，动态库能不能被加载是一个大问题。heif-converter 在 Jar 包里动态解压.so、.dylib、.dll的策略我很中意，减少了很多本该存在的痛苦。
3. 核心实操——用 heif-converter 完成 HEIC 到 PNG/JPEG 的转换
3.1 Maven 依赖引入
项目用的 Spring Boot 2.7，JDK 1.8，理论上 JDK 8 往上都能跑。先在pom.xml里引入 heif-converter 依赖：
<dependency> <groupId>io.github.oliver-bach</groupId> <artifactId>heif-converter</artifactId> <version>2.0.0</version> </dependency>这个库的坐标有时候会变化，建议以 Maven 中央仓库的实际搜索结果为准。引入之后，Maven 会自动把对应平台的 native 库拉下来，我所用的 2.0.0 版本在我的 Intel Mac 和 Ubuntu 20.04 服务器上都能正常加载。如果你在 macOS 上遇到Error loading library之类的提示，多半是动态库和本机架构不匹配，这时候检查一下系统是 x86_64 还是 arm64，换对应版本依赖即可。
3.2 核心转换代码实现
下面是我在项目中实际可用的最小代码片段。先看这一版，我再逐行解释：
import io.github.oliver_bach.heifconverter.HeifConverter; import java.io.File; import java.io.FileInputStream; import java.io.InputStream; import java.nio.file.Files; import java.nio.file.Path; public class HeicConvertUtil { public static File convertToJpeg(Path heicPath, Path outputDir) throws Exception { File output = new File(outputDir.toFile(), heicPath.getFileName().toString().replace(".heic", ".jpg")); try (InputStream input = new FileInputStream(heicPath.toFile())) { HeifConverter.heifToJpeg(input, output); } return output; } public static File convertToPng(Path heicPath, Path outputDir) throws Exception { File output = new File(outputDir.toFile(), heicPath.getFileName().toString().replace(".heic", ".png")); try (InputStream input = new FileInputStream(heicPath.toFile())) { HeifConverter.heifToPng(input, output); } return output; } }这里有两个关键方法：HeifConverter.heifToJpeg(InputStream, File)和HeifConverter.heifToPng(InputStream, File)。第一个参数传 HEIC 的输入流，第二个参数是输出文件对象。库内部会做解码、像素格式转换、编码三步操作。你可能好奇为什么不直接传字节数组，我的经验是传 InputStream 在大文件场景下更省内存，它内部是流式处理的，不会一次性把整个 HEIC 读进堆内存。
不过有一点要注意：heifToJpeg输出的 JPEG 背景默认是白色的，heifToPng会保留透明通道。听起来很合理，但实际测试时我发现，当 HEIC 本身是从截图工具导出、带透明信息时，转 PNG 会完整保留，但转 JPEG 时透明部分会变成黑色。如果你不想出现黑底，建议在转 JPEG 前先用 Java 2D 把图像画到一张白底图片上，或者直接改用 RGB 模式的转换。这是个非常微妙但真实存在的坑。
3.3 批量转换与目录处理
单个文件转完了还不够，真实项目里经常是一整个目录的 HEIC 等着转换。我通常这样处理：
public static void batchConvert(Path sourceDir, Path targetDir) throws Exception { if (!Files.exists(targetDir)) { Files.createDirectories(targetDir); } Files.walk(sourceDir) .filter(Files::isRegularFile) .filter(p -> p.toString().toLowerCase().endsWith(".heic")) .forEach(p -> { try { File output = new File(targetDir.toFile(), p.getFileName().toString().replace(".heic", ".jpg")); try (InputStream input = Files.newInputStream(p)) { HeifConverter.heifToJpeg(input, output); } } catch (Exception e) { // 这里我建议记录失败文件路径，不要中断整个任务 System.err.println("转换失败: " + p + " -> " + e.getMessage()); } }); }批量转换时最怕的就是一个坏文件导致整个队列挂起。我的习惯是把异常捕获放在单文件级别，转换失败的单独记录日志，最后统一汇总，而不是一旦出现 IOException 就直接中断。另外Files.walk会递归遍历子目录，配合filter可以精准筛选出 HEIC 文件，不乱动其他格式。输出目录如果不存在，记得先创建，否则 FileOutputStream 会直接抛 FileNotFoundException。
3.4 重命名策略与文件名兼容性
HEIC 文件的命名通常是以IMG_1234.HEIC这种风格出现的，注意后缀大小写不固定。我上面的例子只替换了.heic，但实际生产中 iOS 导出的 HEIC 后缀很可能是大写.HEIC。我在工具类里有个正则，把大小写都覆盖到：
public static String replaceHeicSuffix(String fileName, String newExt) { return fileName.replaceAll("(?i)\\.heic$", newExt); }这样不管输入是IMG_1234.HEIC还是IMG_1234.heic，输出都是IMG_1234.jpg。虽然是小细节，却能帮你免掉后端接 OSS 时因为文件名大小写不一致而多写的一堆判断逻辑。
4. 生产环境避坑指南——那些文档里不会写的事
4.1 方向信息丢失：旋转问题
iPhone 拍摄的 HEIC 文件大部分是横着存传感器数据的，方向信息放在 EXIF Orientation 字段里。按理说解码后自动应用方向才是我们想要的效果，但实际测试发现，部分 libheif 的构建版本并不会自动处理 Orientation，导致你转换出来的 JPEG 是“躺着的”，需要看图软件自己旋转。
如果遇到这种情况，单独用 Java 的 ImageIO 读输出 JPEG 后，获取"orientation"属性并手动旋转 90°、180° 或 270°。老实说，这个坑在不同的 libheif 版本里表现差异很大，我在 Ubuntu 上编译的动态库就正常，macOS 上却有旋转问题。我最终的解决方案是转换完检查目标格式的元数据，必要时用ImageIO重新写入。
4.2 高分辨率大图的内存压力
1800 万像素以上的照片，解码出来是 6000x4000 左右的 ARGB 像素矩阵，一个像素 4 字节，算下来一张图解码完就可能吃掉 100MB 上下。如果同时并发转 10 张图，JVM 堆内存直接见顶，GC 压力巨大，搞不好 OOM。
我心里有两个红线：一是限制后端同时转换的线程数，我用了一个固定大小为 4 的线程池，把并发控制住；二是对超大分辨率做一些降采样策略，比如先解析 HEIC 的宽高信息，如果超过 4000px，就把输出 JPEG 的压缩质量调低一些，或者用渐进式压缩来减少最终图片的大小。
实测下来，线程池设为 4 的时候，CPU 利用率能维持在 70% 左右，堆内存稳定在 1GB 内，不会出现频繁 Full GC。如果你把线程数调到 8，CPU 会飙升到 100%，而且系统响应会明显变慢，收益不升反降。这一点在不同机器上可能不同，建议压测后定参数。
4.3 动态库加载异常与容器部署
Linux 服务器上最常遇到的异常是java.lang.UnsatisfiedLinkError: no heif in java.library.path或者类似libheif.so: cannot open shared object file。这种基本就是系统里没有安装 libheif 的依赖或动态库。Ubuntu/Debian 下先装libheif1和libheif-dev：
apt-get update && apt-get install -y libheif1 libheif-dev用 Docker 的话，把这个命令写进 Dockerfile 就行。但是注意，不要图省事直接用 alpine 镜像，因为 alpine 用的是 musl libc，而 heif-converter 的动态库很可能依赖 glibc，部署后加载动态库会报Error loading shared library libheif.so.1: No such file or directory。我当时在这上面耗了大半天，最后老老实实改成eclipse-temurin:8-jre这种基于 Ubuntu 的基础镜像才消停。
另外如果你同时用到了多个需要 native 库的组件，还要留意动态库之间的依赖冲突。比如有些项目引了 OpenCV，它也会解压一堆 .so 文件，有可能和 heif-converter 的 .so 命名冲突。这种问题定位很费劲，最实际的建议是隔离部署环境，或者升级到最新版本确认官方有没有处理。
4.4 常见异常排查速查表
我把项目周期里遇到的典型异常和处理方案整理成了表格，方便快速定位：
| 异常现象 | 可能原因 | 解决方案 |
|---|---|---|
UnsatisfiedLinkError: no heif in java.library.path | 系统缺少 libheif 动态库 | 安装 libheif1 / libheif-dev，确认 .so 能被找到 |
Error loading library在 macOS 上出现 | arm64 与 x86_64 架构不匹配 | 更换与 CPU 架构对应的 heif-converter 版本 |
IOException: Failed to decode HEIF | 输入文件不是合法 HEIC，或是 HEVC 编码规格不兼容 | 先用系统工具验证文件格式，必要时换解码方案 |
| 输出 JPEG 方向颠倒 | libheif 未应用 EXIF Orientation | 在 Java 层读取 orientation，手动旋转 |
| 转换高分辨率图 OOM | 堆内存不足 | 调整 Xmx，限制并发线程数 |
| 转换速度极慢 | 服务器 CPU 不支持硬件解码 | 考虑升级 CPU，或降低单图分辨率 |
4.5 关于性能和压缩参数的调整
heif-converter 默认的 JPEG 输出质量是 90，如果你对存储成本敏感，可以找找库内部有没有暴露 quality 参数。我用过的一些版本里，只有固定质量的转换方法，所以如果你想要自定义质量，还得在转换后用 ImageIO 重新压缩一次。这也是一个性能开销点，但是可控。比如：
BufferedImage image = ImageIO.read(jpegFile); ImageWriter writer = ImageIO.getImageWritersByFormatName("jpg").next(); ImageWriteParam param = writer.getDefaultWriteParam(); param.setCompressionMode(ImageWriteParam.MODE_EXPLICIT); param.setCompressionQuality(0.8f); try (ImageOutputStream ios = ImageIO.createImageOutputStream(new File(newFile))) { writer.setOutput(ios); writer.write(null, new IIOImage(image, null, null), param); }这样可以把体积再压缩一些。不过说实话，HEIC 转 JPEG 本身已经经过了两次有损编码，能维持 85 的压缩质量，人眼就基本看不出区别了，没必要为了极致的体积去拉低质量。
5. 从实际项目复盘，我对这个转换方案的思考
这次做 HEIC 转换服务，我最大的收获不是会调 API，而是理解了“格式兼容”这件事在服务端的本质：不追求万能，而是要在标准化、性能和兼容三者之间找平衡点。
整套方案落地后，我们的服务端可以顺滑地接收 iPhone 上原图直传的 HEIC 照片，然后统一转换成 JPEG 用于网页端展示，转成 PNG 用于需要透明背景的贴纸合图场景。上线之后，用户反馈从“图片传不上去”变成了“上传速度怎么变快了”，因为 HEIC 体积小，上传耗时自然缩短。这就是格式优化带来的连锁效应。
根据我个人的使用体验，这条技术路线如果后续想扩展，还能做两件事：一是接入图片审核服务时，把 HEIC 转成 JPEG 再送审，避免审核系统不识别；二是如果未来有 AVIF 的需求，libheif 本身也支持 AVIF 解码，底层方案可以复用。
最后分享一个小技巧：如果你只是临时想验证某张 HEIC 能不能正常解码，不要急着写 Java 代码，直接用系统的magick identify input.HEIC命令看一眼，能识别就说明 libheif 装好了，再回 Java 里排查会更快。踩过几次坑之后，我发现这种快速验证方式能帮你节省大量排错时间，别一上来就闷头写转换代码。
本文还有配套的精品资源，点击获取
