本文详解如何将 Spring Boot 项目打包为标准可复用的 Java 库（非 fat-jar），解决 IntelliJ 无法识别类、Gradle 引入后无代码提示等问题。核心在于禁用 Spring Boot 的重打包机制，改用 maven-jar-plugin 生成符合 Maven 规范的普通 JAR。
本文详解如何将 spring boot 项目打包为标准可复用的 java 库（非 fat-jar），解决 intellij 无法识别类、gradle 引入后无代码提示等问题。核心在于禁用 spring boot 的重打包机制，改用 `maven-jar-plugin` 生成符合 maven 规范的普通 jar。
在开发中，我们常需将通用工具类、业务组件或内部 SDK 封装为自定义依赖供其他项目复用。但若原始项目是 Spring Boot 工程，默认执行 mvn install 生成的是 fat-jar（即包含所有依赖、主类及 BOOT-INF/ 目录结构的可执行包），这类 JAR 不符合 Maven 标准依赖规范——其字节码实际嵌套在 BOOT-INF/classes/ 下，导致 IDE（如 IntelliJ）和构建工具（如 Gradle）无法正确解析类路径，进而出现“能编译但无代码补全”“导入报红”等典型问题。
✅ 正确做法：生成标准 Java Library JAR
你需要显式禁用 spring-boot-maven-plugin 的 repackage 目标，并配置 maven-jar-plugin 输出纯净的 class 文件结构（即 com/example/MyUtil.class 直接位于 JAR 根目录下）。在自定义库项目的 pom.xml 中添加如下配置：
<build>
<plugins>
<!-- 关键：禁用 Spring Boot 默认的 repackage 行为 -->
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<skip>true</skip>
</configuration>
</plugin>
<!-- 生成标准 JAR（非 fat-jar） -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<version>3.3.0</version>
<configuration>
<!-- 确保打包 src/main/java 编译输出的 class 文件 -->
<classesDirectory>${project.build.outputDirectory}</classesDirectory>
<!-- 可选：添加 MANIFEST.MF 元信息（如需指定主类） -->
<archive>
<manifest>
<addClasspath>true</addClasspath>
<classpathPrefix>lib/</classpathPrefix>
<!-- 若该库本身不运行，mainClass 可省略 -->
<!-- <mainClass>com.example.Application</mainClass> -->
</manifest>
</archive>
</configuration>
</plugin>
</plugins>
</build>⚠️ 注意事项：
- 必须设置
<skip>true</skip>禁用spring-boot-maven-plugin，否则它会在package阶段覆盖maven-jar-plugin的输出；- 不要使用
<packaging>jar</packaging>以外的类型（如pom或war）；- 确保
src/main/java下有有效 Java 类，且maven-compiler-plugin版本兼容 JDK（推荐 3.11.0+）；- 执行
mvn clean install后，检查本地 Maven 仓库（如~/.m2/repository/com/yourgroup/your-artifact/1.0.0/）中生成的xxx-1.0.0.jar是否直接包含.class文件（可用jar -tf xxx.jar | head -20验证）。
? 在 Gradle 项目中正确引用
生成标准 JAR 后，推荐通过 Maven 本地仓库方式 引入（而非 fileTree），以保障依赖传递性与 IDE 索引完整性：
// build.gradle (Gradle 8.0+)
repositories {
mavenLocal() // 优先读取本地 .m2
mavenCentral()
}
dependencies {
implementation 'com.yourcompany:your-custom-lib:1.0.0'
}✅ 优势：
- IntelliJ 自动识别依赖并索引源码（若同时发布
-sources.jar，可进一步启用跳转）； - 支持依赖传递（如你的库依赖了
commons-lang3，下游项目自动继承）； - 便于后续迁移到私有 Nexus/Artifactory。
? 提示：若暂未发布到远程仓库，仅本地测试，可配合
maven-publish插件一键发布到mavenLocal()：<!-- pom.xml 中补充 --> <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-source-plugin</artifactId> <version>3.2.1</version> <executions> <execution> <id>attach-sources</id> <goals><goal>jar-no-fork</goal></goals> </execution> </executions> </plugin> </plugins> </build>再执行
mvn clean source:jar install，即可让 IDE 加载源码与 Javadoc。
✅ 验证是否成功
- 在 Gradle 项目中
import com.yourpackage.YourClass;—— 不再报红； - 按
Ctrl + 点击（Windows/Linux）或Cmd + 点击（macOS）可跳转至该类定义； - 在终端执行
./gradlew dependencies | grep your-artifact，确认依赖树中存在且状态为resolved。
遵循以上流程，你就能将 Spring Boot 项目安全、规范地转化为可被任意 Java/Gradle 项目无缝集成的自定义依赖，彻底告别 fileTree 引入导致的 IDE 失效与维护隐患。
