本文详解如何正确打包 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。
在开发中，我们常需将通用功能（如工具类、公共 DTO、客户端 SDK）抽离为独立模块，并作为自定义依赖供其他项目复用。但若该模块是 Spring Boot 项目，默认执行 mvn install 生成的是 fat-jar（即包含 BOOT-INF/classes/ 结构的可执行包），其类文件被嵌套在 BOOT-INF 目录下，不符合标准 Java 类路径规范——这正是 IntelliJ 无法解析、Gradle 编译通过却无代码补全的根本原因。
✅ 正确做法：生成标准结构 JAR（非 Spring Boot 可执行包）
你需要显式禁用 spring-boot-maven-plugin 的 repackage 目标，并配置 maven-jar-plugin 直接打包 target/classes 下的编译产物（即标准 com/example/MyClass.class 路径结构）。
在自定义库项目的 pom.xml 中，替换或补充 <build></build> 配置如下：
<build><!-- 关键：彻底禁用 Spring Boot 的 repackage，避免生成 BOOT-INF --><plugins><plugin><groupid>org.springframework.boot</groupid><artifactid>spring-boot-maven-plugin</artifactid><configuration><skip>true</skip><!-- 禁用 repackage --></configuration></plugin><!-- 生成标准 JAR：classes 直接位于根路径 --><plugin><groupid>org.apache.maven.plugins</groupid><artifactid>maven-jar-plugin</artifactid><version>3.3.0</version><configuration><classesdirectory>${project.build.outputDirectory}</classesdirectory><!-- 可选：添加 MANIFEST.MF 元信息（非必需） --><archive><manifest><addclasspath>false</addclasspath><mainclass></mainclass></manifest></archive></configuration></plugin></plugins></build>
? 提示：
<skip>true</skip>比移除插件更安全，确保不会意外触发重打包；maven-jar-plugin默认即从target/classes打包，因此classesDirectory配置通常可省略，但显式声明更清晰。
执行 mvn clean install 后，你将在 target/ 目录下得到标准 JAR（如 my-utils-1.0.0.jar），解压可见：
com/mycompany/utils/StringUtils.class ← 直接暴露，IDE 可索引 META-INF/MANIFEST.MF
? Gradle 项目中正确引用
在你的 Gradle 项目（如 build.gradle）中，切勿使用 fileTree 或手动添加 JAR（这绕过依赖管理，导致 IDE 无法解析源码与文档）：
❌ 错误方式（无 IDE 支持、无传递依赖）：
implementation fileTree(dir: 'libs', include: ['my-utils-*.jar'])
✅ 正确方式：发布到本地 Maven 仓库后，按坐标引用（推荐）：
// build.gradle (Kotlin DSL 示例)
dependencies {
implementation 'com.mycompany:my-utils:1.0.0' // 坐标需与 pom.xml 中 <groupid><artifactid><version> 一致
}</version></artifactid></groupid>
并在 settings.gradle 中启用本地仓库（若未配置）：
pluginManagement {
repositories {
mavenLocal() // 优先检查本地 ~/.m2/repository
gradlePluginPortal()
}
}
⚠️ 注意事项与验证步骤
-
必须执行
mvn clean install：仅mvn compile不会生成 JAR，mvn install才会安装到本地 Maven 仓库（~/.m2/repository/）。 -
检查坐标一致性：确保
pom.xml中的<groupid></groupid>,<artifactid></artifactid>,<version></version>与 Gradle 中implementation坐标完全匹配（大小写敏感）。 -
刷新 IDE 缓存：IntelliJ 中执行
File → Reload project或点击 Gradle 工具栏的 ? 图标；必要时File → Invalidate Caches and Restart。 -
验证 JAR 内容：用
jar -tf target/my-utils-1.0.0.jar | head -20确认类路径是否为扁平结构（无BOOT-INF/）。 -
进阶建议：长期维护建议将库发布至私有 Nexus/Artifactory，或使用
maven-publish插件生成完整元数据（含 POM、sources、javadoc）。
完成上述配置后，你的自定义库将像任何中央仓库依赖一样，在 Gradle 编译、IDE 代码补全、跳转、重构中完全可用——真正实现“一次构建，多处复用”。
