Ruoyi若依框架整合本地JAR包：Spring Boot Maven插件配置实战

1. 问题背景：本地JAR包为何在打包时消失？

最近在用Ruoyi框架开发项目时，遇到一个典型问题：本地引入的JAR包在开发调试时一切正常，但执行maven package生成部署包时，这些依赖就像变魔术一样消失了。相信不少朋友都踩过这个坑——明明在pom.xml里用<systemPath>指定了JAR路径，运行时也不报错，为什么最终打包会漏掉这些依赖？

以我最近的项目为例，需要在系统模块引入一个第三方签章工具包（usign-util-1.1.jar）。按照常规做法，我在pom.xml配置了如下依赖：

xml复制<dependency>
    <groupId>com.usign</groupId>
    <artifactId>usign-util</artifactId>
    <version>1.1</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/lib/usign-util-1.1.jar</systemPath>
</dependency>

开发阶段完全没问题，但打包部署后服务直接报ClassNotFoundException。打开生成的war包一看，lib目录下果然没有这个JAR文件。这其实是Spring Boot Maven插件默认行为：system作用域的依赖默认不会被打包。这种设计原本是为了避免将系统环境相关的依赖混入应用包，但在使用本地JAR时就成了拦路虎。

2. 那些年我们踩过的坑：无效解决方案盘点

在找到正确解法前，我先尝试了网上常见的几种方案，结果全是坑。这里分享出来帮大家避雷：

2.1 错误尝试一：修改maven-compiler-plugin配置

有些教程建议在maven-compiler-plugin中添加extdirs配置：

xml复制<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.1</version>
    <configuration>
        <compilerArguments>
            <extdirs>${project.basedir}/lib/usign-util-1.1.jar</extdirs>
        </compilerArguments>
    </configuration>
</plugin>

实测发现这完全无效，还会引发警告："should not point at files within the project directory"。因为这个配置本意是指定扩展类库目录，而不是单个JAR文件。

2.2 错误尝试二：使用maven-install-plugin安装本地JAR

另一种流行方案是通过maven-install-plugin将JAR安装到本地仓库：

xml复制<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-install-plugin</artifactId>
    <version>2.5.2</version>
    <executions>
        <execution>
            <phase>clean</phase>
            <configuration>
                <file>${basedir}/lib/usign-util-1.1.jar</file>
                <groupId>com.usign</groupId>
                <artifactId>usign-util</artifactId>
                <version>1.1</version>
            </configuration>
            <goals>
                <goal>install-file</goal>
            </goals>
        </execution>
    </executions>
</plugin>

这个方案理论上可行，但存在严重缺陷：

1. 需要先移除<scope>和<systemPath>，导致开发环境直接报错
2. 多模块项目需要每个开发者手动执行install
3. 污染本地Maven仓库，团队协作时容易混乱

3. 终极解决方案：spring-boot-maven-plugin的正确配置

经过反复试验，最终解决方案其实非常简单——在spring-boot-maven-plugin中启用includeSystemScope。具体操作分三步：

3.1 项目结构准备

1. 在system模块下创建lib目录（如ruoyi-system/src/main/resources/lib）
2. 将第三方JAR文件（如usign-util-1.1.jar）放入该目录
3. 保持原有的依赖声明不变

3.2 关键插件配置

在需要打包的模块（通常是admin模块）的pom.xml中，找到spring-boot-maven-plugin配置，添加<includeSystemScope>true</includeSystemScope>：

xml复制<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <configuration>
                <includeSystemScope>true</includeSystemScope>
            </configuration>
        </plugin>
    </plugins>
</build>

3.3 完整配置示例

结合Ruoyi框架特点，建议使用如下完整配置：

xml复制<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <version>2.6.3</version>
            <configuration>
                <fork>true</fork>
                <includeSystemScope>true</includeSystemScope>
            </configuration>
            <executions>
                <execution>
                    <goals>
                        <goal>repackage</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-war-plugin</artifactId>
            <version>3.3.2</version>
            <configuration>
                <failOnMissingWebXml>false</failOnMissingWebXml>
            </configuration>
        </plugin>
    </plugins>
    <finalName>${project.artifactId}</finalName>
</build>

4. 原理剖析与进阶技巧

4.1 为什么includeSystemScope能解决问题？

Spring Boot Maven插件在打包时默认会过滤掉system作用域的依赖，这是为了防止将系统环境相关的JAR（如JDK工具包）打包进应用。通过设置includeSystemScope=true，我们告诉插件："这些system范围的JAR是我们主动引入的，请保留它们"。

4.2 多模块项目的注意事项

在Ruoyi这类多模块项目中，需要特别注意：

1. 本地JAR应该放在实际使用的模块（如system模块）
2. 插件配置要放在最终打包的模块（如admin模块）
3. 如果多个模块需要独立打包，每个模块都需要配置

4.3 版本兼容性指南

不同版本的Spring Boot Maven插件行为略有差异：

• 2.0.x版本：需要显式配置includeSystemScope
• 2.1.x及以上：参数行为更稳定
• 最新3.x版本：建议测试验证

4.4 备选方案对比

虽然includeSystemScope是最佳方案，但其他方法也有适用场景：

5. 常见问题排查手册

5.1 JAR包已配置但依然缺失

检查步骤：

1. 确认JAR文件路径是否正确
2. 检查插件配置是否在正确模块
3. 执行mvn clean package确保全新构建
4. 查看打包日志是否有警告信息

5.2 出现ClassNotFoundException

可能原因：

1. 依赖的依赖没有传递（需要手动引入）
2. JAR文件损坏（重新下载或获取）
3. 类加载问题（检查war包结构）

5.3 与其他插件冲突

如果同时使用maven-assembly-plugin等工具，可能需要额外配置：

xml复制<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-assembly-plugin</artifactId>
    <configuration>
        <includeSystemScope>true</includeSystemScope>
    </configuration>
</plugin>

6. 最佳实践建议

经过多个项目实践，我总结出以下经验：

1. 尽量将本地JAR放在resources/lib目录下，保持项目结构清晰
2. 在团队协作时，建议将本地JAR提交到版本控制
3. 对于常用第三方JAR，最好搭建私有Nexus仓库替代本地依赖
4. 每次引入新本地JAR后，立即验证打包结果
5. 在CI/CD流程中，确保构建服务器也有相同的JAR文件路径

记得第一次遇到这个问题时，我花了整整一天时间排查。现在回头看，解决方案其实很简单，但如果没有理解背后的原理，下次遇到类似问题可能还会踩坑。技术文档的质量参差不齐，关键是要学会验证和思考——这也是我写下这篇实战指南的初衷。