本文以多模块 Gradle 项目为例，5 步完成 nebula-support 的接入。

环境要求

工具	版本要求
JDK	17+
Gradle	8.12+
Nexus（私服）	可访问内网地址

---

Step 1：配置插件仓库

在根项目 settings.gradle 的 pluginManagement.repositories 中，配置插件 JAR 的拉取地址（私服优先）。

pluginManagement {
    repositories {
        // 私服（优先）：nebula-boot-plugin-gradle JAR 从此处拉取
        maven {
            name = 'nexus-public'
            url = 'http://10.10.1.130:8081/repository/oys-public/'
            allowInsecureProtocol = true
        }
        // 阿里云镜像（备用）
        maven { url = 'https://maven.aliyun.com/repository/gradle-plugin' }
        gradlePluginPortal()
    }
}

提示

pluginManagement 专门用于解析插件 JAR，与项目依赖的 repositories 配置相互独立。

---

Step 2：引入构建插件

根据项目结构选择引入方式。

多模块项目（推荐）

// 根 build.gradle
buildscript {
    repositories {
        mavenLocal()
        maven { url "https://maven.aliyun.com/repository/public/" }
    }
    dependencies {
        // 替换为实际发布版本
        classpath "com.huida.nebula.support:nebula-boot-plugin-gradle:${nebulaPluginVersion}"
    }
}

allprojects {
    apply plugin: 'com.huida.nebula.plugin.boot'
    // ...
}

单模块项目

// build.gradle
plugins {
    id 'com.huida.nebula.plugin.boot'
}

---

Step 3：配置 nebula {} 块

在 allprojects（或单模块的 build.gradle）中配置插件扩展。以下是推荐的最小化配置：

allprojects {
    group = 'com.example'
    version = projectVersion    // 从 gradle.properties 读取

    apply plugin: 'com.huida.nebula.plugin.boot'

    nebula {
        // BOM 版本，对应 nebula-support-dependencies 的发布版本
        nebulaVersion = nebulaBootVersion

        // 是否启用 Spring 依赖管理 + BOM 导入（默认 true，保持即可）
        enableDependencyManagement = true

        // 是否自动配置仓库（默认 true，保持即可）
        enableRepositoryConfiguration = true

        // 私服是否可访问：内网可访问时保持 true，否则设为 false
        enablePrivateRepo = true

        // 是否发布框架模块到 Nexus（业务项目不需要，设为 false 或省略）
        // enablePublish = true
    }
}

哪些配置可以省略？

enableDependencyManagement、enableRepositoryConfiguration、enableCommonConfiguration、enableTest 均默认为 true，无需显式配置。

---

Step 4：配置发布凭据

凭据不要写在项目的 build.gradle 或 gradle.properties 中（防止提交到版本库），应写在本机全局配置。支持两种方式，任选其一即可。

方式一：~/.gradle/gradle.properties

# 文件不存在则新建

# 发布到 Nexus 的凭据
nebula.publish.username=your-nexus-username
nebula.publish.password=your-nexus-password

# 私服拉取凭据（如果私服需要登录）
# nebula.private.username=your-nexus-username
# nebula.private.password=your-nexus-password

方式二：~/.m2/settings.xml

在 <servers> 中配置 Nexus 凭据，便于与 Maven 共用；<server><id> 需与构建中使用的仓库标识一致。

<settings>
  <servers>
    <server>
      <id>nexus</id>
      <username>your-nexus-username</username>
      <password>your-nexus-password</password>
    </server>
  </servers>
</settings>

安全提示

~/.gradle/gradle.properties 与 ~/.m2/settings.xml 仅存在于本机，不会被纳入版本控制。切勿将密码写入项目内的任何配置文件。

---

Step 5：验证构建

# 验证编译通过
./gradlew build

# 查看项目版本与环境信息（输出 Nebula 插件版本 + Java/Gradle 版本）
./gradlew printVersion

# 查看当前管理的依赖版本
./gradlew dependencyVersions

---

常见问题

01. 私服无法访问，构建挂起

nebula {
    enablePrivateRepo = false   // 跳过私服，直接走阿里云镜像
}

02. 出现 "allowInsecureProtocol" 警告

插件已对 http:// 开头的私服地址自动开启 allowInsecureProtocol = true，不需要手动配置。若警告来自 settings.gradle 的 pluginManagement，则按 Step 1 示例补上即可。

03. nebulaVersion 未配置，BOM 未导入

检查 gradle.properties 是否存在对应属性：

# gradle.properties（根项目）
nebula.version=0.1.2-SNAPSHOT   # nebula-support-dependencies 版本

或在 nebula {} 中显式指定：

nebula {
    nebulaVersion = '0.1.2-SNAPSHOT'
}

04. Gradle Configuration Cache 报错

升级 nebula-boot-plugin-gradle 到最新版本。插件已针对 Gradle Configuration Cache 做了兼容处理，旧版本可能存在兼容问题。

05. 多模块项目中某个子模块不想使用插件功能

在该子模块的 build.gradle 中单独关闭对应功能：

nebula {
    enableCommonConfiguration = false   // 关闭公共依赖注入
    enableDependencyManagement = false  // 关闭 BOM 管理
}