本文详解如何在无网络环境下通过 Gradle 离线模式（--offline）成功加载本地 Spring Boot 等第三方插件，重点解决插件命名规范、buildscript 依赖声明、配套工具类库缺失及 Maven 本地仓库复用等核心问题。
本文详解如何在无网络环境下通过 gradle 离线模式（`--offline`）成功加载本地 spring boot 等第三方插件，重点解决插件命名规范、`buildscript` 依赖声明、配套工具类库缺失及 maven 本地仓库复用等核心问题。
在 Gradle 离线构建场景中（如内网 CI/CD、安全隔离环境），仅将插件 JAR 文件放入本地目录并不足以让 plugins { } 块正常工作——Gradle 插件解析机制有严格约定，且插件自身往往依赖大量间接类库。若处理不当，会报错如 Plugin [...] was not found in any of the following sources 或运行时 ClassNotFoundException（例如 org.springframework.boot.loader.tools.MainClassFinder）。以下为经过生产验证的完整解决方案。
✅ 正确配置本地插件的三步法
1. 遵循 Gradle 插件坐标命名规范
Gradle 在解析 id 'org.springframework.boot' version '2.2.0.RELEASE' 时，实际查找的 Maven 坐标是：
org.springframework.boot:org.springframework.boot.gradle.plugin:2.2.0.RELEASE
而非 org.springframework.boot:spring-boot-gradle-plugin:2.2.0.RELEASE（这是旧式 buildscript 写法对应的 artifactId）。同理，io.spring.dependency-management 对应的坐标是：
io.spring.dependency-management:io.spring.dependency-management.gradle.plugin:1.0.11.RELEASE
因此，你放入 plugins/ 目录的 JAR 文件名必须与该坐标完全匹配（推荐重命名）：
# 正确命名（关键！） plugins/ ├── org.springframework.boot-org.springframework.boot.gradle.plugin-2.2.0.RELEASE.jar └── io.spring.dependency-management-io.spring.dependency-management.gradle.plugin-1.0.11.RELEASE.jar
? 提示：JAR 文件名格式为 {group}-{module}-{version}.jar，其中 module = {pluginId}.gradle.plugin。可使用 jar -tf xxx.jar | head -5 检查其 META-INF/gradle-plugins/ 下的插件属性文件是否匹配。
2. 使用 buildscript + flatDir 声明本地插件（兼容离线）
plugins { } 块在离线模式下对 flatDir 支持有限，强烈建议改用传统 buildscript 方式，并显式配置 flatDir 仓库：
// build.gradle
buildscript {
repositories {
// 优先尝试 flatDir；若需更多依赖，可追加 mavenLocal()
flatDir {
dirs 'plugins' // 指向你的 plugins/ 目录
}
mavenLocal() // 可选：配合后续 .m2 复用
}
dependencies {
// 注意：此处使用标准 Maven 坐标，与 JAR 文件名一致
classpath 'org.springframework.boot:org.springframework.boot.gradle.plugin:2.2.0.RELEASE'
classpath 'io.spring.dependency-management:io.spring.dependency-management.gradle.plugin:1.0.11.RELEASE'
// ⚠️ 必须添加：spring-boot-loader-tools 是 bootJar 任务的核心依赖
classpath 'org.springframework.boot:spring-boot-loader-tools:2.2.0.RELEASE'
}
}
// 启用插件（注意：不再用 plugins { } 块）
apply plugin: 'org.springframework.boot'
apply plugin: 'io.spring.dependency-management'
apply plugin: 'java'3. 补齐插件运行时依赖（关键难点）
Spring Boot Gradle 插件在执行 bootJar 时，会动态加载 spring-boot-loader-tools、spring-boot 核心库、甚至 groovy, slf4j 等传递依赖。这些不能仅靠 plugins/ 目录解决，因为：
- 插件 JAR 本身不包含其全部 runtime classpath；
- Gradle 构建脚本引擎（Gradle DSL）和插件逻辑在不同 ClassLoader 中运行。
✅ 推荐方案：复用已有的 .m2/repository
- 在联网环境（如开发机）执行一次完整构建：./gradlew build --no-daemon；
- 将生成的 ~/.m2/repository 整个目录复制到目标离线机器的相同路径；
- 在 build.gradle 中启用 mavenLocal()（如上所示），确保插件能解析所有传递依赖。
? 验证技巧：若仍报 ClassNotFoundException，可通过 ./gradlew --debug bootJar 2>&1 | grep "Resolving" 查看 Gradle 实际尝试下载/加载的坐标，再补全对应 JAR 到 .m2 或 libs/。
? 注意事项与最佳实践
- ❌ 不要混用 plugins { } 块与 buildscript —— 离线模式下二者行为不一致，统一用 buildscript 更可靠；
- ✅ settings.gradle 中的 pluginManagement { } 仅影响 plugins { } 块，离线时建议移除或仅保留 mavenLocal()；
- ? spring-boot-loader-tools 是 bootJar 的刚需依赖，必须显式声明在 buildscript.classpath 中；
- ? 若无法复制整个 .m2，可使用 mvn dependency:copy-dependencies 按需导出依赖树，但工作量显著增加；
- ?️ 安全合规场景：所有 JAR 应预先通过哈希校验（如 SHA-256）确保来源可信。
通过以上配置，即可在完全断网环境中稳定执行 ./gradlew build --offline 和 ./gradlew bootJar --offline，真正实现企业级离线构建闭环。
