本文详解在无网络环境下，通过 --offline 模式构建 Spring Boot 项目时，如何正确配置本地插件（如 spring-boot-gradle-plugin），包括插件命名规范、buildscript 依赖声明、必需的传递依赖（如 spring-boot-loader-tools）及离线依赖管理最佳实践。
本文详解在无网络环境下，通过 `--offline` 模式构建 spring boot 项目时，如何正确配置本地插件（如 `spring-boot-gradle-plugin`），包括插件命名规范、`buildscript` 依赖声明、必需的传递依赖（如 `spring-boot-loader-tools`）及离线依赖管理最佳实践。
Gradle 的插件解析机制与传统依赖不同：当使用 plugins { id 'org.springframework.boot' version '2.2.0.RELEASE' } 声明时，Gradle 实际会尝试解析为 Maven 坐标形式——即 ${pluginId}:${pluginId}.gradle.plugin:${pluginVersion}。这意味着：
- org.springframework.boot → 解析为 org.springframework.boot:org.springframework.boot.gradle.plugin:2.2.0.RELEASE
- io.spring.dependency-management → 解析为 io.spring.dependency-management:io.spring.dependency-management.gradle.plugin:1.0.11.RELEASE
因此，仅将 spring-boot-gradle-plugin-2.2.0.RELEASE.jar 放入 plugins/ 目录是无效的，因为文件名不匹配 Gradle 插件仓库的坐标约定，且 flatDir 不支持插件元数据（如 plugin.xml）的自动发现。
✅ 正确做法是弃用 plugins {} 块（它强制走插件仓库解析），改用传统 buildscript {} + apply plugin: 方式，并显式声明符合坐标的 classpath 依赖：
// build.gradle
buildscript {
repositories {
// 优先从本地目录加载插件 JAR（无需联网）
flatDir {
dirs 'plugins' // 指向存放重命名后 JAR 的目录
}
// 可选：同时支持 mavenLocal()（若已安装到 ~/.m2）
mavenLocal()
}
dependencies {
// 注意：此处必须使用完整 Maven 坐标格式的名称
classpath name: 'spring-boot-gradle-plugin', version: '2.2.0.RELEASE'
classpath name: 'dependency-management-plugin', version: '1.0.11.RELEASE'
// ⚠️ 关键依赖：spring-boot-loader-tools 是 bootJar 任务运行所必需
classpath name: 'spring-boot-loader-tools', version: '2.2.0.RELEASE'
}
}
// 应用插件（注意：ID 保持不变，与插件 JAR 内部 META-INF/gradle-plugins/*.properties 一致）
apply plugin: 'org.springframework.boot'
apply plugin: 'io.spring.dependency-management'
apply plugin: 'java'? 插件目录结构需严格对应坐标（以 spring-boot-gradle-plugin-2.2.0.RELEASE.jar 为例）：
请将其重命名为：
plugins/spring-boot-gradle-plugin-2.2.0.RELEASE.jar → ✅ 保留原名即可（flatDir 依赖 name: 属性，不依赖文件名）
但更推荐统一按 groupId-artifactId-version.jar 命名，例如：
plugins/org.springframework.boot-org.springframework.boot.gradle.plugin-2.2.0.RELEASE.jar
（实际只要 buildscript.dependencies.classpath name: 与 JAR 文件名或 flatDir 中存在的文件名一致即可）
? 关键注意事项：
- spring-boot-gradle-plugin 本身存在强传递依赖，尤其是 spring-boot-loader-tools（提供 MainClassFinder 等核心类）。缺失该依赖会导致 bootJar 或 bootRun 执行失败（报 NoClassDefFoundError）。务必一并放入 plugins/ 并声明 classpath。
- flatDir 仓库不解析 POM 或传递依赖，所有依赖（包括插件自身的依赖）都必须手动下载并放入 plugins/ 目录，或通过其他方式（如预置 ~/.m2）提供。
- 若插件依赖过多（如 spring-boot-gradle-plugin 依赖 spring-boot, gradle-api, commons-lang3 等），完全手动收集所有 JAR 极其繁琐且易遗漏。此时推荐更稳健的离线方案：
- 在有网环境执行一次完整构建（./gradlew build --refresh-dependencies），确保所有依赖缓存至 ~/.gradle/caches/ 和 ~/.m2/repository/；
- 将整个 ~/.m2/repository 目录复制到离线机器的相同路径；
- 在 build.gradle 中启用 mavenLocal() 并禁用远程仓库（如注释掉 mavenCentral()）；
- 使用 --offline 构建，Gradle 将自动从本地 Maven 仓库解析插件与依赖。
? 总结：
在纯离线场景中，不要依赖 plugins {} 块 + flatDir，因其无法满足插件元数据和传递依赖需求。应采用 buildscript {} 显式管理插件 JAR，并确保：
- 插件 JAR 文件名与 classpath name: 匹配；
- 所有运行时必需的传递依赖（特别是 spring-boot-loader-tools）均已就位；
- 对于复杂项目，优先采用「预缓存 ~/.m2」方案，而非手动维护 plugins/ 目录——后者维护成本高、可靠性低，仅适用于极简插件场景。
