Gradle 2.x 构建、多模块与发布流水线¶

IntelliJ Platform Gradle Plugin 2.x 是当前官方推荐的插件构建工具。它负责解析目标 IDE、下载平台依赖、运行开发实例、测试、验证、签名和发布。旧的 Gradle IntelliJ Plugin 1.x 已不再积极开发，新项目应使用 2.x。

当前最低要求¶

截至 2026-06-18 官方文档：

项	最低要求
IntelliJ Platform	2023.3
Gradle	9.0.0
Java Runtime	17
Gradle plugin ID	`org.jetbrains.intellij.platform`
官方示例版本	`2.16.0`

目标平台为 2024.2+ 时，插件编译和运行通常要按 Java 21 处理。不要把 Gradle JVM、编译 target、IDE 运行时混成一个概念。

三类 Gradle 插件¶

插件 ID	用途
`org.jetbrains.intellij.platform`	主插件模块，创建运行、构建、验证、签名、发布等任务
`org.jetbrains.intellij.platform.module`	多模块插件的子模块，避免子模块重复创建主任务
`org.jetbrains.intellij.platform.settings`	在 `settings.gradle.kts` 的 dependency resolution 中声明 IntelliJ 仓库

主模块：

plugins {
    id("org.jetbrains.intellij.platform") version "2.16.0"
}

子模块：

plugins {
    id("org.jetbrains.intellij.platform.module")
}

仓库配置¶

最常用：

repositories {
    mavenCentral()
    intellijPlatform {
        defaultRepositories()
    }
}

如果使用 dependencyResolutionManagement：

// settings.gradle.kts
import org.jetbrains.intellij.platform.gradle.extensions.intellijPlatform

plugins {
    id("org.jetbrains.intellij.platform.settings") version "2.16.0"
}

dependencyResolutionManagement {
    repositoriesMode = RepositoriesMode.FAIL_ON_PROJECT_REPOS
    repositories {
        mavenCentral()
        intellijPlatform {
            defaultRepositories()
        }
    }
}

当不使用 defaultRepositories() 时，要按需显式加入 releases()、snapshots()、marketplace()、localPlatformArtifacts() 等仓库，否则本地 IDE、捆绑插件或 Marketplace 插件可能无法解析。

目标平台声明¶

固定 IDEA 版本：

dependencies {
    intellijPlatform {
        intellijIdea("2026.1.3")
    }
}

参数化：

platformType=IC
platformVersion=2026.1.3

dependencies {
    intellijPlatform {
        val type = providers.gradleProperty("platformType")
        val version = providers.gradleProperty("platformVersion")
        create(type, version)
    }
}

使用本地 IDE：

dependencies {
    intellijPlatform {
        local("/Applications/IntelliJ IDEA.app")
    }
}

EAP 版本通常不是 installer 依赖。需要 EAP 时，关注 useInstaller = false 的配置，同时注意非 installer archive 不包含 JetBrains Runtime。

插件依赖¶

捆绑插件：

dependencies {
    intellijPlatform {
        bundledPlugin("com.intellij.java")
    }
}

Marketplace 插件：

dependencies {
    intellijPlatform {
        plugin("org.intellij.scala", "2024.1.4")
    }
}

普通第三方库仍使用标准 Gradle 依赖：

dependencies {
    implementation("com.fasterxml.jackson.core:jackson-databind:2.17.2")
}

运行时还必须在 plugin.xml 中声明依赖。Gradle 依赖解决编译和沙盒依赖；plugin.xml 依赖决定 IDE 是否加载插件。

多模块插件¶

根模块使用 platform 插件，子模块使用 module 插件。子模块默认继承根模块的目标 IntelliJ Platform。

依赖打包规则：

根模块的 api、implementation、runtimeOnly 项目依赖会自动作为 plugin modules 打包到 lib/modules/。
只有需要把某模块 class 合并进主插件 JAR 时，才使用 pluginComposedModule(dependency)。
签名、发布、运行 IDE 等任务放在根模块管理。

建议结构：

plugin-root/
  build.gradle.kts
  settings.gradle.kts
  src/main/resources/META-INF/plugin.xml
  core/
  language/
  product-java/
  product-js/
  frontend/
  backend/
  shared/

多模块不是为了“显得架构化”，而是为了隔离可选依赖、产品专属 API、Remote Development 前后端和大型功能边界。

常用任务¶

任务	用途
`runIde`	启动开发实例
`buildPlugin`	构建插件 ZIP
`signPlugin`	签名插件
`verifyPlugin`	基础验证
`runPluginVerifier`	运行 Plugin Verifier
`publishPlugin`	发布到 Marketplace
`printBundledPlugins` / `listBundledPlugins`	查看目标 IDE 捆绑插件
`generateSplitModeRunConfigurations`	生成 Split Mode 运行配置

发布配置¶

intellijPlatform {
    pluginConfiguration {
        ideaVersion {
            sinceBuild = "261"
        }
    }

    signing {
        certificateChain = providers.environmentVariable("CERTIFICATE_CHAIN")
        privateKey = providers.environmentVariable("PRIVATE_KEY")
        password = providers.environmentVariable("PRIVATE_KEY_PASSWORD")
    }

    publishing {
        token = providers.gradleProperty("intellijPlatformPublishingToken")
        channels = listOf("beta")
    }
}

不要把 token、私钥、证书密码写入仓库。多行密钥在 CI 中通常用 Base64 编码后传入。

CI 流水线建议¶

Pull Request：

./gradlew test
./gradlew buildPlugin
./gradlew verifyPlugin

Release candidate：

./gradlew test
./gradlew buildPlugin
./gradlew runPluginVerifier
./gradlew signPlugin

Release：

./gradlew publishPlugin

发布策略：

PR 不需要签名和发布密钥。
beta/eap 渠道先验证，再发默认渠道。
版本号必须递增。
每次升级目标 IDE 后更新 verifier matrix。
多产品插件至少覆盖每个目标产品。

常见故障¶

现象	常见原因
编译能过，运行 `NoClassDefFoundError`	忘记 `plugin.xml <depends>`
解析不到捆绑插件	没有 `bundledPlugin()` 或仓库缺 `localPlatformArtifacts()`
EAP 解析失败	installer dependency 不含 EAP，需要调整 `useInstaller`
子模块创建了重复发布任务	子模块误用了 `org.jetbrains.intellij.platform`
Plugin Verifier 报 unresolved	依赖库错误打包或目标 IDE 缺依赖
CI 能构建，本地 IDE 没源码	IDE 未启用 Gradle 下载源码或 Plugin DevKit 过旧