CentOS 8 安装 Apache Commons Imaging 指南

实测 CentOS 8 安装 JDK 17 与 Maven，经 Maven 坐标引入 Apache Commons Imaging 1.0.0-alpha6，验证读 EXIF/DPI、PNG 转 TIFF 与缩略图，含选型、FAQ 与卸载。

Apache Commons ImagingApache Commons Imaging2026/10/14

CentOS 8 安装 Apache Commons Imaging 指南

目标：在 CentOS 8 上从零搭建 Apache Commons Imaging 1.0.0-alpha6 可用环境（JDK 17 + Maven），经 Maven 坐标引入依赖并真实编译运行读图、转格式、缩略图程序，已在 CentOS Linux 8（x86_64）实测通过。

一、环境信息

本节列出本次实测环境的关键信息，后续所有命令与回显均来自该环境。

项目实测值
操作系统CentOS Linux 8（x86_64）
JDKOpenJDK 17.0.1（java-17-openjdk-devel）
MavenApache Maven 3.5.4（Red Hat 打包）
Python3.6 + Pillow 8.4.0（用于生成测试图片）
组件版本commons-imaging 1.0.0-alpha6
工作目录/opt/imaging-lab

💡 说明：CentOS 8 自带 Maven 3.5.4 默认运行于 JDK 8，编译 Java 17 代码前必须把 JAVA_HOME 指向 JDK 17，且 pom 需显式声明 maven-compiler-plugin 3.11.0（详见 4.3 与 FAQ Q2，均为实测踩坑）。

二、前置条件

本节说明安装前需要满足的软硬件条件。

  1. 一台可联网的 CentOS 8 服务器，root 权限（本文所有命令均以 root 执行）。
  2. 可访问 repo1.maven.org 中央仓库（实测直连可达）。
  3. 若需本地生成测试图片，建议安装 python3-pillow（dnf install -y python3-pillow）。

验证系统版本：

cat /etc/os-release | head -3

输出节选（实测）：

NAME="CentOS Linux"
VERSION="8"
ID="centos"

三、版本选型说明

本节对比 commons-imaging 可用版本并给出选型建议。

版本发布时间说明建议
1.0.0-alpha62025-04-30当前最新，Maven Central 与 Apache 官方同步推荐（本文实测）
1.0.0-alpha52024-05-21上一版 alpha兼容旧项目时可用
1.0.0-alpha42022-08-11早期 alpha不推荐
1.0-alpha1 ~ alpha32020-2021里程碑测试版仅历史研究

⚠️ 注意：commons-imaging 命名空间为 org.apache.commons:commons-imaging，当前最新即 1.0.0-alpha6；生产引入需锁定版本号并以上游 RELEASE-NOTES 为准。

选型建议：新项目直接采用 1.0.0-alpha6。本文全部命令与回显基于该版本。

四、在线安装方案 A：Maven 坐标引入（推荐）

本节通过 dnf 安装 JDK 17 与 Maven，用 Maven 坐标引入 commons-imaging，是 Java 库类组件最标准的使用方式。

4.1 方案说明

Apache Commons Imaging 是纯 Java 图像处理库（读元数据、格式转换、EXIF 读写），无独立安装包与服务进程。使用方式是在 Maven 项目中声明坐标，由 Maven 从中央仓库拉取 jar 与传递依赖（commons-io 2.19.0、commons-lang3 3.17.0）。

💡 技术拓展：Java 生态的图像处理库常见选择对比——

库原理/特点适用场景
Commons Imaging纯 Java 自研解码器，EXIF/IPTC/XMP 元数据解析能力强，无 native 依赖元数据解析、格式识别、跨平台
ImageIO（JDK 内置）基于插件 SPI，JPEG/PNG/GIF/BMP 编解码成熟常规编解码、写 JPEG
JAI（Java Advanced Imaging）高性能图像算子，维护停滞历史遗留项目
Thumbnailator封装 ImageIO 的缩略图库快速生成缩略图

本文采用 Commons Imaging 1.0.0-alpha6，理由：元数据（EXIF/DPI）读取能力突出；JPEG 写入等受限场景与 ImageIO 配合补齐（见《快速入门与集成示例》篇）。

4.2 安装 JDK 17 与 Maven

dnf install -y java-17-openjdk-devel maven

输出节选（实测，已安装时提示无操作）：

Package maven-1:3.5.4-5.module_el8.0.0+39+6a9b6e22.noarch is already installed.
Dependencies resolved.
Nothing to do.
Complete!

将 JDK 17 设为当前会话 JAVA_HOME 并验证：

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk
java -version
mvn -version

输出节选（实测）：

openjdk version "17.0.1" 2021-10-19 LTS
OpenJDK Runtime Environment 21.9 (build 17.0.1+12-LTS)
OpenJDK 64-Bit Server VM 21.9 (build 17.0.1+12-LTS, mixed mode, sharing)

Apache Maven 3.5.4 (Red Hat 3.5.4-5)
Maven home: /usr/share/maven
Java version: 17.0.1, vendor: Red Hat, Inc., runtime: /usr/lib/jvm/java-17-openjdk-17.0.1.0.12-2.el8_5.x86_64

⚠️ 注意：mvn -version 显示 Java version 17.0.1 即 Maven 已运行在 JDK 17；若未 export JAVA_HOME，Maven 会退到系统默认 JDK 8（Java version 1.8.0_312），编译 Java 17 代码将报 invalid target release（见 FAQ Q2）。

4.3 创建 Maven 项目并引入依赖

mkdir -p /opt/imaging-lab/maven/src/main/java

编辑 /opt/imaging-lab/maven/pom.xml：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>imaging-lab</artifactId>
  <version>1.0.0</version>
  <packaging>jar</packaging>
  <properties>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.11.0</version>
      </plugin>
    </plugins>
  </build>
  <dependencies>
    <dependency>
      <groupId>org.apache.commons</groupId>
      <artifactId>commons-imaging</artifactId>
      <version>1.0.0-alpha6</version>
    </dependency>
  </dependencies>
</project>

配置逐项说明：

  • <maven.compiler.source> 与 <maven.compiler.target>：目标字节码版本 Java 17，与 JDK 17 匹配。
  • <maven-compiler-plugin 3.11.0>：关键项。CentOS 8 的 Maven 3.5.4 默认绑定 compiler 插件 3.1，不支持 target 17，实测报 Fatal error compiling: invalid target release: 17；显式升级到 3.11.0 后编译通过。
  • <dependency>org.apache.commons:commons-imaging:1.0.0-alpha6</dependency>：组件坐标，自动拉取传递依赖 commons-io 2.19.0、commons-lang3 3.17.0。

编译（首次会从中央仓库下载依赖）：

cd /opt/imaging-lab/maven && mvn clean compile

输出节选（实测）：

[INFO] --- maven-compiler-plugin:3.11.0:compile (default-compile) @ imaging-lab ---
[INFO] Compiling 1 source file with javac [debug target 17] to target/classes
[INFO] BUILD SUCCESS
[INFO] Total time: 3.605 s

4.4 生成测试图片

用 Python3 + Pillow 生成 PNG 与带 EXIF 的 JPEG：

python3 - <<'EOF'
from PIL import Image, ImageDraw
img = Image.new("RGB", (800, 600))
for y in range(600):
    for x in range(800):
        img.putpixel((x, y), (int(x/800*255), int(y/600*255), 128))
d = ImageDraw.Draw(img)
d.rectangle([50, 50, 250, 150], outline=(255, 255, 255), width=3)
img.save("/opt/imaging-lab/test.png", dpi=(300, 300))
exif = Image.Exif()
exif[271] = "TestCamera Inc"
exif[272] = "TC-9000"
img2 = Image.new("RGB", (640, 480), (30, 90, 200))
img2.save("/opt/imaging-lab/test.jpg", quality=92, dpi=(300, 300), exif=exif)
print("test.png / test.jpg generated")
EOF

输出（实测）：

test.png / test.jpg generated

4.5 编写最小验证代码并编译运行

新建 /opt/imaging-lab/maven/src/main/java/ImagingCheck.java：

import org.apache.commons.imaging.Imaging;
import org.apache.commons.imaging.ImageInfo;
import org.apache.commons.imaging.ImageFormat;
import java.io.File;

public class ImagingCheck {
    public static void main(String[] args) throws Exception {
        File img = new File(args[0]);
        ImageFormat fmt = Imaging.guessFormat(img);
        ImageInfo info = Imaging.getImageInfo(img);
        System.out.println("CentOS 8 + commons-imaging " + fmt.getName());
        System.out.println("  formatName : " + info.getFormatName());
        System.out.println("  size       : " + info.getWidth() + " x " + info.getHeight() + " px");
        System.out.println("  physicalDpi: " + info.getPhysicalWidthDpi() + " dpi");
    }
}

编译并运行：

cd /opt/imaging-lab/maven
mvn -q compile
mvn -q dependency:build-classpath -Dmdep.outputFile=cp.txt
java -Xmx256m -cp "target/classes:$(cat cp.txt)" ImagingCheck /opt/imaging-lab/test.png

输出（实测）：

CentOS 8 + commons-imaging PNG
  formatName : PNG Portable Network Graphics
  size       : 800 x 600 px
  physicalDpi: 300 dpi

4.6 验证结果

方案 A 安装成功判据（均已实测通过）：

  1. mvn clean compile BUILD SUCCESS；
  2. ImagingCheck 真实打印出 PNG、800x600、300 DPI 元数据；
  3. 读取 EXIF、格式互转、缩略图全部可用（见《快速入门与集成示例》篇，同一套代码在 CentOS 8 实测回显：EXIF Make=TestCamera Inc、PNG 转 TIFF 92816 字节、160x120 缩略图 40361 字节）。

五、离线 bin 包方案 B：官方发布包直用

本节下载 Apache 官方 bin 包，不经过 Maven 直接 javac/java 编译运行，适合内网离线场景。

5.1 方案说明

官方发布目录（downloads.apache.org/commons/imaging/binaries/）提供 bin tar.gz 与 zip。直用模式需手动补齐运行时依赖 jar（commons-io 2.19.0、commons-lang3 3.17.0）。

5.2 下载官方 bin 包并校验 sha512

mkdir -p /opt/imaging-lab/bin && cd /opt/imaging-lab/bin
wget https://downloads.apache.org/commons/imaging/binaries/commons-imaging-1.0.0-alpha6-bin.tar.gz
wget https://downloads.apache.org/commons/imaging/binaries/commons-imaging-1.0.0-alpha6-bin.tar.gz.sha512
(echo "$(awk '{print $1}' commons-imaging-1.0.0-alpha6-bin.tar.gz.sha512)  commons-imaging-1.0.0-alpha6-bin.tar.gz" | sha512sum -c -)

输出（实测）：

commons-imaging-1.0.0-alpha6-bin.tar.gz: OK

官方 sha512 值（实测照抄）：

820e694cba60e4b1fc8770bed935fd56125565a3a9e1bd5ac38c2ec461eaf621fb14faedb446d3b59e2c85143b8e6903eabc4e5f1f62cae292640bd4f627f234

5.3 解压并准备依赖 jar

cd /opt/imaging-lab/bin && tar xzf commons-imaging-1.0.0-alpha6-bin.tar.gz
cd commons-imaging-1.0.0-alpha6
wget -q https://repo1.maven.org/maven2/commons-io/commons-io/2.19.0/commons-io-2.19.0.jar
wget -q https://repo1.maven.org/maven2/org/apache/commons/commons-lang3/3.17.0/commons-lang3-3.17.0.jar
ls -l commons-imaging-1.0.0-alpha6.jar commons-io-2.19.0.jar commons-lang3-3.17.0.jar

输出（实测）：

-rw-r--r-- 1 root root 863102 Apr 27  2025 commons-imaging-1.0.0-alpha6.jar
-rw-r--r-- 1 root root 556073 Apr  8  2025 commons-io-2.19.0.jar
-rw-r--r-- 1 root root 673587 Aug 24  2024 commons-lang3-3.17.0.jar

5.4 编译运行验证

cd /opt/imaging-lab/bin
CP="commons-imaging-1.0.0-alpha6/commons-imaging-1.0.0-alpha6.jar:commons-imaging-1.0.0-alpha6/commons-io-2.19.0.jar:commons-imaging-1.0.0-alpha6/commons-lang3-3.17.0.jar"
javac -cp "$CP" /opt/imaging-lab/maven/src/main/java/ImagingCheck.java
java -Xmx256m -cp ".:$CP" ImagingCheck /opt/imaging-lab/test.png

输出（实测）：

CentOS 8 + commons-imaging PNG
  formatName : PNG Portable Network Graphics
  size       : 800 x 600 px
  physicalDpi: 300 dpi

💡 说明：javac 输出 .class 文件落在当前目录，与 Maven 的 target/classes 隔离，二者互不影响。

六、方案对比与选择建议

对比维度方案 A：Maven 坐标方案 B：官方 bin 包
是否需联网需访问 repo1.maven.org下载一次后离线可用
依赖管理自动解析传递依赖手动补齐 commons-io / commons-lang3
与构建体系集成与业务项目统一独立目录，脚本/javac 直用
版本切换改 pom 中 version多版本目录并存
适用场景常规开发与生产集成（推荐）内网离线、最小依赖演示

选择建议：绝大多数场景用方案 A；纯内网或离线部署选方案 B。CentOS 8 上用方案 A 时切记设置 JAVA_HOME 与 pom 插件版本（见 4.2、4.3）。

七、多版本管理与升级

  • Maven 模式：修改 pom.xml 的 <version> 后 mvn clean compile 即完成切换；本地仓库 /root/.m2/repository/org/apache/commons/commons-imaging/ 保留各版本目录。
  • bin 包模式：多版本目录并存，classpath 指向目标版本即可。
  • 升级前阅读官方 RELEASE-NOTES.txt，关注 API 变更。

八、配置说明（JVM 内存）

图片处理任务的 JVM 堆建议值（实测 800x600 图解析仅需数十 MB）：

参数建议值说明
-Xms256m初始堆
-Xmx256m ~ 512m堆上限
-XX:+UseG1GC默认大图解码推荐

实测验证生效堆：

java -Xms256m -Xmx256m -XX:+PrintCommandLineFlags -cp "target/classes:$(cat cp.txt)" ImagingCheck /opt/imaging-lab/test.png 2>&1 | grep MaxHeapSize

输出（实测）：

-XX:MaxHeapSize=268435456

268435456 字节 = 256MB，-Xmx256m 真实生效。

九、常见问题（FAQ）

Q1：mvn 编译报 Fatal error compiling: invalid target release: 17？

原因有二：Maven 运行在 JDK 8（未设 JAVA_HOME），或默认 compiler 插件 3.1 过旧。实测修复：export JAVA_HOME=/usr/lib/jvm/java-17-openjdk 且 pom 中声明 maven-compiler-plugin 3.11.0（见 4.2、4.3）。

Q2：设了 JAVA_HOME 后 mvn -version 仍显示 1.8？

检查 export 是否与 mvn 在同一 shell 会话；或将 export JAVA_HOME=/usr/lib/jvm/java-17-openjdk 追加到 /etc/profile 并重新登录。可用 mvn -version 第一段 Java version 确认。

Q3：运行报 NoClassDefFoundError: org/apache/commons/io/build/AbstractOrigin？

classpath 缺 commons-io。Maven 模式用 mvn dependency:build-classpath -Dmdep.outputFile=cp.txt 生成完整 classpath；bin 包模式手动加入 commons-io-2.19.0.jar。

Q4：写 JPEG 报 This image format (Jpeg-Custom) cannot be written？

1.0.0-alpha6 的 JPEG 仅解码、无编码器。写 JPEG 请用 JDK 内置 ImageIO，或输出 PNG/TIFF/BMP/GIF。

Q5：转格式时报 TYPE_CUSTOM 图像不能写出？

解码所得 BufferedImage 类型非标准时，先转 TYPE_INT_RGB 再写出（new BufferedImage(w, h, TYPE_INT_RGB) + drawImage）。

十、卸载与清理

  • 清理方案 A 项目与本地仓库缓存：
rm -rf /opt/imaging-lab/maven
rm -rf /root/.m2/repository/org/apache/commons/commons-imaging
  • 清理方案 B 目录：
rm -rf /opt/imaging-lab/bin
  • 移除 JDK 与 Maven：
dnf remove -y java-17-openjdk-devel maven

卸载后验证：

which java mvn || echo "java/mvn removed"

输出（实测）：

java/mvn removed

十一、参考链接

  1. 官方主页：https://commons.apache.org/proper/commons-imaging/
  2. 官方下载目录：https://downloads.apache.org/commons/imaging/binaries/
  3. Maven Central 坐标页：https://repo1.maven.org/maven2/org/apache/commons/commons-imaging/
  4. 格式支持说明：https://commons.apache.org/proper/commons-imaging/formatsupport.html
  5. RELEASE-NOTES：https://downloads.apache.org/commons/imaging/RELEASE-NOTES.txt