在日常 Java 开发中，我们经常会遇到一些第三方库没有发布到 Maven 中央仓库的情况，比如商业库 Aspose.Words。
本文将介绍在 Windows 环境的 IDEA 中引入本地 Jar 包的常规方式，以及部署到 Linux 环境 后出现报错的原因与最终解决方案。

一、背景介绍

项目中需要使用 Aspose.Words for Java 来处理 Word 文档，例如文档转换、格式化导出等功能。
由于该库未开源且未发布到公共 Maven 仓库，我们只能采用 本地 Jar 包引用 的方式。

Jar 文件路径如下：

src/main/resources/lib/aspose-words-15.8.0-jdk16.jar

二、在 Windows IDEA 中引入本地 Jar

在 pom.xml 中通过 <dependency> 标签引入本地 Jar 的方式如下：

<dependency>
    <groupId>asposeword</groupId>
    <artifactId>asposewordsdk</artifactId>
    <version>1.0</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/src/main/resources/lib/aspose-words-15.8.0-jdk16.jar</systemPath>
</dependency>

✅ 说明：
scope=system 表示该依赖不会从远程仓库下载，而是直接从本地路径加载。
systemPath 必须是一个绝对路径或相对于项目根目录的路径。

这种方式在 Windows 本地开发环境下运行一切正常，项目可以顺利启动并使用 Aspose 相关功能。

三、部署到 Linux 后出现问题

当将项目打包后部署到 Linux 服务器上时，启动报错，提示类似以下信息：

java.lang.ExceptionInInitializerError
Caused by: java.io.FileNotFoundException: 
   /home/project/src/main/resources/lib/aspose-words-15.8.0-jdk16.jar (No such file or directory)

问题原因很明显：

• 使用 systemPath 引入的本地 Jar 不会被 Maven 打入最终的 jar 或 war 包中；

• 当项目在 Linux 上运行时，该路径并不存在，因此依赖无法加载。

四、解决方案：将 Jar 安装到本地 Maven 仓库

最稳妥的做法是将第三方 Jar 文件安装到本地 Maven 仓库中，并像普通依赖一样引用。

在命令行中执行以下命令：

mvn install:install-file \
-Dfile="F:/Desktop/aspose-words-15.8.0-jdk16.jar" \
-DgroupId=com.aspose \
-DartifactId=aspose-words \
-Dversion=15.8.0 \
-Dpackaging=jar

执行成功后，Maven 会将该 Jar 文件安装到本地仓库（通常位于 ~/.m2/repository/com/aspose/aspose-words/15.8.0）。

五、在项目中引入依赖

此时，我们只需在 pom.xml 中添加普通的依赖声明即可：

<dependency>
    <groupId>com.aspose</groupId>
    <artifactId>aspose-words</artifactId>
    <version>15.8.0</version>
</dependency>

然后重新打包部署到 Linux 后，项目可正常运行，Aspose.Words 功能恢复正常。