从0到1：JetBrains 插件开发系列（二）

环境搭建与你的第一个 Hello World 插件

作者：于天惠

在上一篇文章中，我们探讨了 JetBrains 插件的价值与可能性，并明确了“插件开发并非高不可攀”。今天，我们将迈出最关键的一步：亲手跑起你的第一个插件。

这一步看似简单，却是整个开发旅程的基石。只有成功搭建环境并看到插件在 IDE 中运行，你才会真正相信——“原来我真的可以扩展 IDEA”。

本文将手把手带你完成：

• • 开发环境准备（JDK + IntelliJ IDEA）
• • 使用官方模板创建插件项目
• • 理解 Gradle 配置与 plugin.xml
• • 运行、调试并验证插件效果

准备好了吗？让我们开始！

一、开发环境准备

JetBrains 插件基于 IntelliJ Platform 构建，其开发工具链高度依赖 JetBrains 自家产品。因此，你需要：

1. 安装 JDK 17（推荐 OpenJDK）

JetBrains 从 2022.1 版本起要求插件使用 JDK 17 编译。建议使用 Eclipse Temurin JDK 17 或 Oracle OpenJDK 17。

验证安装：

java -version# 应输出类似：openjdk version "17.0.12" 2024-07-16

⚠️ 注意：不要使用 JDK 21+，除非你明确知道目标 IDE 支持。目前主流插件仍以 JDK 17 为基准。

2. 安装 IntelliJ IDEA（Community 或 Ultimate）

虽然你日常可能用 PyCharm 或 WebStorm，但开发插件必须使用 IntelliJ IDEA，因为它是 IntelliJ Platform 最完整的实现。

• • 下载地址：https://www.jetbrains.com/idea/download/
• • Community 版完全免费且足够用于插件开发。

安装后，确保你能正常启动 IDEA 并创建 Java/Kotlin 项目。

二、创建插件项目：使用官方模板

JetBrains 官方提供了一个 Gradle 模板项目，极大简化了初始配置。我们直接复用它。

步骤 1：克隆模板仓库

打开终端，执行：

git clone https://github.com/JetBrains/intellij-platform-plugin-template.git jb-hello-plugincd jb-hello-plugin

💡 建议将此项目重命名为 jb-hello-plugin 或你喜欢的名字。

步骤 2：用 IDEA 打开项目

在 IDEA 中选择 File > Open，选中刚克隆的文件夹。IDEA 会自动识别 Gradle 项目并导入依赖。

首次导入可能需要几分钟（会下载 IntelliJ Platform SDK 和 Gradle 依赖）。

三、理解项目结构

导入成功后，你会看到如下关键文件：

jb-hello-plugin/├── build.gradle.kts          # Gradle 构建脚本（Kotlin DSL）├── gradle.properties         # 插件元信息（版本、ID 等）├── src/main/kotlin/          # Kotlin 源码目录│   └── MyPluginAction.kt     # 示例 Action 类└── src/main/resources/    └── META-INF/        └── plugin.xml        # 插件声明文件（核心！）

关键文件解析

1. gradle.properties

定义插件基本信息：

pluginGroup = com.examplepluginName = hello-pluginpluginVersion = 0.0.1pluginSinceBuild = 241pluginUntilBuild = 243.*

• • pluginSinceBuild / pluginUntilBuild：指定兼容的 IDE 版本范围（241 = 2024.1）。
• • 这些值后续可发布时调整。

2. build.gradle.kts

这是构建脚本的核心，由 JetBrains 的 gradle-intellij-plugin 提供支持。关键配置包括：

intellij {    version.set("2024.1")      // 基于哪个版本的 IDEA 开发    type.set("IC")             // IC = IntelliJ IDEA Community}

你几乎不需要修改它，除非要支持其他 IDE（如 PyCharm → type = "PC"）。

3. plugin.xml

插件的“身份证”和“功能清单”。默认内容如下：

<idea-plugin>    <name>Hello Plugin</name>    <id>com.example.hello-plugin</id>    <actions>        <action id="HelloAction"                class="com.example.MyPluginAction"                text="Say Hello"                description="Greet the user">            <add-to-group group-id="ToolsMenu" anchor="first"/>        </action>    </actions></idea-plugin>

• • <actions> 声明了一个菜单项。
• • add-to-group group-id="ToolsMenu" 表示将该操作添加到 Tools 菜单顶部。

4. MyPluginAction.kt

这是响应用户点击的逻辑：

class MyPluginAction : AnAction() {    overridefun actionPerformed(e: AnActionEvent) {        val message = "Hello from your first plugin!"        Messages.showMessageDialog(e.project, message, "Hello", Messages.getInformationIcon())    }}

• • 继承 AnAction 是创建菜单/按钮的标准方式。
• • Messages.showMessageDialog 是平台提供的弹窗 API。

四、运行你的插件

现在，激动人心的时刻到了！

方法：使用 Gradle 任务启动沙箱 IDE

在 IDEA 右侧 Gradle 工具窗口 中，展开：

Tasks > intellij > runIde

双击 runIde，或在终端执行：

./gradlew runIde

系统会启动一个 全新的 IDEA 实例（沙箱环境），其中已预装你的插件。

📌 沙箱 IDE 的特点：

• • 不会影响你日常使用的主 IDE
• • 插件以开发模式加载，支持热重载
• • 用户设置、插件状态独立隔离

验证插件是否生效

1. 1. 在沙箱 IDEA 中，点击顶部菜单栏 Tools
2. 2. 你会看到第一项是 “Say Hello”
3. 3. 点击它，弹出对话框：“Hello from your first plugin!”

🎉 恭喜！你刚刚成功开发并运行了第一个 JetBrains 插件！

五、调试与热重载

开发过程中，你肯定需要反复修改代码并测试。JetBrains 提供了高效的调试支持。

调试步骤：

1. 1. 在 MyPluginAction.kt 中某行打上断点（如 val message = ...）
2. 2. 在 Gradle 工具窗口中运行 runIde 的 Debug 模式（右键 → Debug）
3. 3. 在沙箱 IDE 中触发插件操作
4. 4. 断点命中，可查看变量、调用栈等

热重载（Reload Changed Classes）

修改代码后，无需重启整个 IDE：

• • 在调试会话中，点击 Run > Reload Changed Classes（或快捷键 Ctrl+Shift+F9）
• • 修改的类会被重新加载，立即生效

⚠️ 注意：如果修改了 plugin.xml 或新增了类，仍需重启 runIde。

六、常见问题排查

Q1：runIde 启动失败，报错 “No compatible IDE found”

• • 检查 build.gradle.kts 中的 intellij.version 是否与本地网络可下载的版本匹配。
• • 可尝试改为 "LATEST-EAP-SNAPSHOT" 获取最新预览版（不推荐长期使用）。

Q2：插件菜单没出现

• • 检查 plugin.xml 中的 group-id 是否正确（ToolsMenu 是标准 ID）
• • 确保类路径与 class 属性一致（包名 + 类名）

Q3：中文乱码或 UI 显示异常

• • 在 gradle.properties 中添加：

  org.gradle.jvmargs=-Dfile.encoding=UTF-8

七、小挑战：动手改一改！

为了巩固所学，请尝试完成以下任务（答案将在下期公布）：

1. 1. 修改弹窗内容：将消息改为 “Hello, [你的名字]! Welcome to plugin dev.”
2. 2. 更换菜单位置：将插件移到 Edit 菜单 的末尾
3. 3. 添加快捷键：为该操作绑定快捷键 Ctrl+Alt+H（Windows/Linux）或 Cmd+Alt+H（macOS）

💡 提示：快捷键配置需在 plugin.xml 的 <action> 内添加：

<keyboard-shortcut keymap="$default$" first-keystroke="ctrl alt H"/>

八、下一步预告

你已经成功迈出了第一步。但一个真正的插件远不止“弹个窗”这么简单。

在下一篇中，我们将深入剖析：

• • 插件项目的核心组成部分
• • Extension Points 与 Services 的工作机制
• • 如何组织代码结构以支持复杂功能

标题预告：《插件项目结构与核心概念解析》

结语：每一个伟大的工具，都始于一行 Hello World

今天，你不仅运行了一个插件，更打开了通往“定制化开发体验”的大门。那些曾经让你皱眉的重复操作、低效流程，未来都可能被你亲手编写的一段代码化解。

记住：你不是在写插件，你是在重塑自己的开发环境。

下期见！