Gradle 离线构建中正确加载本地 Spring Boot 插件的完整方案

本文详解如何在无网络环境下，通过本地插件目录（plugins/）和 buildscript 块正确加载 spring-boot-gradle-plugin 及其全部依赖，解决 --offline 模式下插件解析失败、类找不到（如 MainClassFinder）等典型问题。

本文详解如何在无网络环境下，通过本地插件目录（`plugins/`）和 `buildscript` 块正确加载 `spring-boot-gradle-plugin` 及其全部依赖，解决 `--offline` 模式下插件解析失败、类找不到（如 `mainclassfinder`）等典型问题。

在 Gradle 离线构建场景（如内网 CI/CD、安全隔离环境）中，仅将插件 JAR 文件放入 plugins/ 目录并配置 flatDir 仓库是不够的。这是因为 Gradle 的 plugins {} 块（即插件 DSL）采用严格的坐标解析规则：它会将 id 'org.springframework.boot' version '2.2.0.RELEASE' 自动映射为 Maven 坐标 org.springframework.boot:org.springframework.boot.gradle.plugin:2.2.0.RELEASE，而非简单匹配文件名 spring-boot-gradle-plugin-2.2.0.RELEASE.jar。若本地 plugins/ 目录中不存在符合该坐标的 JAR 文件，即使物理文件存在，Gradle 仍会报错“Plugin was not found”。

✅ 正确做法：弃用 plugins {}，改用 buildscript + 显式坐标声明

plugins {} 块不支持直接引用任意路径的 JAR，也不支持 flatDir 作为插件仓库（pluginManagement.repositories 中的 flatDir 在离线模式下对插件 DSL 无效）。唯一可靠的方式是回归传统 buildscript 块，并确保：

1. 插件 JAR 命名与坐标严格匹配；
2. 所有传递依赖（尤其是 spring-boot-loader-tools）一并纳入；
3. 使用 files() 或 fileTree() 显式引入本地 JAR，避免依赖远程解析。

✅ 步骤一：重命名插件 JAR 以匹配 Gradle 插件坐标

根据 Gradle 插件解析规则，将原始 JAR 重命名为标准 Maven 坐标格式：

? 提示：坐标格式为 ${group}-${artifactId}-${version}.jar，其中 artifactId 是插件 ID 的点号转连字符形式（如 io.spring.dependency-management → io.spring.dependency-management），且必须含 .gradle.plugin 后缀（见 Gradle Plugin Portal 规范）。

✅ 步骤二：配置 buildscript 块，显式声明 classpath

修改 build.gradle，完全移除 plugins {} 块，改用以下方式：

// build.gradle
buildscript {
    repositories {
        // 禁用所有远程仓库，仅保留本地来源
        mavenLocal()
        // 不要使用 maven { url 'plugins' } —— plugins/ 不是合法 Maven 仓库
    }

    dependencies {
        // ✅ 正确：使用 files() 直接引用重命名后的 JAR
        classpath files('plugins/org.springframework.boot-org.springframework.boot.gradle.plugin-2.2.0.RELEASE.jar')
        classpath files('plugins/io.spring.dependency-management-io.spring.dependency.management.gradle.plugin-1.0.11.RELEASE.jar')

        // ⚠️ 必须添加：spring-boot-loader-tools（否则 bootJar 失败）
        classpath files('plugins/spring-boot-loader-tools-2.2.0.RELEASE.jar')

        // ✅ 可选但推荐：将整个 plugins/ 目录作为 classpath（自动包含所有依赖）
        // classpath fileTree(dir: 'plugins', include: '*.jar')
    }
}

// ✅ 应用插件（注意：此处 id 必须与插件元数据一致）
apply plugin: 'org.springframework.boot'
apply plugin: 'io.spring.dependency-management'
apply plugin: 'java'

group = 'com.example'
version = '1.0.0-SNAPSHOT'
sourceCompatibility = '1.8'

repositories {
    mavenLocal()
}

dependencies {
    implementation files('libs/xxx.jar', 'libs/others_of_libs.jar')
}

? 验证插件坐标：可通过解压 JAR 查看 META-INF/gradle-plugins/org.springframework.boot.properties 内容，确认 implementation-class 是否存在，且 group 与 artifactId 匹配。

Rezi.ai

一个使用 AI 自动化创建简历平台

下载

✅ 步骤三：处理插件运行时依赖（关键！）

Spring Boot 插件（如 bootJar）在执行时会动态加载大量工具类（如 org.springframework.boot.loader.tools.MainClassFinder），这些类来自 spring-boot-loader-tools 等子模块。它们不会被 buildscript.classpath 自动传递到插件运行时类路径。

因此，必须确保：

• spring-boot-loader-tools-2.2.0.RELEASE.jar 已放入 plugins/ 并被 classpath files(...) 引入；
• 若仍有 NoClassDefFoundError，说明还缺其他传递依赖（如 spring-core, spring-beans 等）。

此时有两种稳健方案：

✅ 推荐组合：buildscript 引入核心插件 JAR + maven { url '../.m2' } 加载全部运行时依赖。

? 注意事项与最佳实践

• ❌ 不要尝试在 settings.gradle 中用 flatDir 配置 pluginManagement.repositories —— 它对 plugins {} 块无效，且 --offline 下无法解析。
• ❌ 不要使用 classpath "group:artifact:version" 形式（如 classpath "org.springframework.boot:spring-boot-gradle-plugin:2.2.0.RELEASE"）—— 这会触发 Gradle 去远程仓库查找，离线必失败。
• ✅ 所有 files() 路径必须是相对于项目根目录的相对路径，且文件必须真实存在。
• ✅ 构建前务必执行 ./gradlew --stop 清理守护进程，避免缓存干扰。
• ✅ 最终验证命令：./gradlew clean bootJar --offline -S（-S 输出详细堆栈，便于定位缺失类）。

通过以上配置，即可在完全断网环境下，稳定、可复现地完成 Spring Boot 项目的离线构建与打包。核心思想是：放弃对插件 DSL 的幻想，拥抱 buildscript 的确定性控制，并将插件及其全部运行时依赖视为普通 Java 依赖进行管理。