创建与运行插件项目¶

创建插件项目有两条主路径：使用 IntelliJ IDEA 的 New Project 向导，或基于 IntelliJ Platform Plugin Template。团队项目更推荐模板，因为它通常包含 CI、Gradle Wrapper 和更完整的工程约定。

环境准备¶

确认以下工具可用：

IntelliJ IDEA，建议使用较新的版本。
Gradle 与 Gradle Wrapper。IntelliJ Platform Gradle Plugin 2.x 当前要求 Gradle 9.0.0 或更高版本。
Plugin DevKit 插件。2023.3 起它不再随 IDE 默认捆绑，需要从 Marketplace 安装。
与目标 IntelliJ Platform 匹配的 JDK。Gradle 运行时至少需要 Java 17；较新的 IDE 平台通常要求使用 Java 21 编译和运行插件。

使用 New Project 向导¶

在 IntelliJ IDEA 中选择 File | New | Project...，然后选择 IDE Plugin。向导会让你填写：

Name 与 Location：项目名和目录。
Group：通常是反向域名，例如 com.example.company。
Artifact：构建产物名。
JDK：必须与目标平台要求一致。

生成后你会看到类似结构：

my-plugin/
  build.gradle.kts
  gradle.properties
  settings.gradle.kts
  gradle/
  src/main/kotlin/
  src/main/resources/META-INF/plugin.xml

Gradle 2.x 最小配置¶

plugins {
    id("java")
    id("org.jetbrains.kotlin.jvm") version "1.9.25"
    id("org.jetbrains.intellij.platform") version "2.16.0"
}

group = "com.example"
version = "0.1.0"

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

dependencies {
    intellijPlatform {
        intellijIdea("2025.2.6.1")
        testFramework(org.jetbrains.intellij.platform.gradle.TestFrameworkType.Platform)
    }
}

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

tasks {
    withType<JavaCompile> {
        sourceCompatibility = "21"
        targetCompatibility = "21"
    }
    withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile> {
        kotlinOptions.jvmTarget = "21"
    }
}

官方文档在 2026-05-11 更新的 IntelliJ Platform Gradle Plugin 2.x 页面中使用 org.jetbrains.intellij.platform 版本 2.16.0。实际项目应定期核对官方页面、Gradle Plugin Portal 或模板仓库，避免复制过期版本。

目标 IDE 与依赖插件¶

目标 IDE 通过 dependencies.intellijPlatform 指定。常见写法：

dependencies {
    intellijPlatform {
        intellijIdea("2025.2.6.1")
        bundledPlugin("com.intellij.java")
        plugin("org.intellij.scala", "2024.1.4")
    }
}

区别：

bundledPlugin()：目标 IDE 中自带的插件，例如 Java 支持。
plugin()：Marketplace 上的第三方或独立插件，需要给出版本。
local()：使用本机安装的 IDE 作为目标平台，适合调试本地特殊版本。

复杂插件可以把目标平台参数放入 gradle.properties：

platformType=IC
platformVersion=2026.1.3

再由构建脚本读取：

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

多模块插件中，根模块使用 org.jetbrains.intellij.platform，子模块使用 org.jetbrains.intellij.platform.module，避免在每个子模块重复创建运行、签名、发布等任务。

运行插件¶

常用命令：

./gradlew runIde

它会启动一个沙盒 IDE 实例，并把当前插件安装进去。调试时使用 IDE 的 Gradle 运行配置或 Debug 运行 runIde。

常见问题¶

找不到 IntelliJ 平台依赖¶

优先检查：

repositories { intellijPlatform { defaultRepositories() } } 是否存在。
Gradle 是否能访问 JetBrains 仓库。
目标 IDE 版本号是否真实存在。

代码中找不到 Java API¶

如果插件要访问 Java PSI、Java 检查或 Java 项目模型，需要同时声明：

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

并在 plugin.xml 中声明依赖：

<depends>com.intellij.modules.java</depends>