简介一份专为IntelliJ IDEA插件开发初学者打造的源码Demo目标读者是希望快速上手IDE扩展功能的Java开发者。资源聚焦菜单点击、弹出框输入、鼠标右键菜单等常见交互场景通过完整可运行示例展示插件从项目搭建到功能响应的全过程。压缩包内共16个文件其中5个Java源文件为核心实现5个XML文件用于插件注册与项目配置2个SVG图标提供明暗主题图标另有iml、gitignore等工程辅助文件整体仅10KB结构紧凑且易于对照学习。已有785人学习或下载适合具备基础Java语法、希望理解IDEA插件Action机制和事件监听流程的开发人员。阅读源码可以掌握如何创建插件项目、在plugin.xml中声明扩展点、编写自定义对话框和弹出框、利用Swing组件实现界面交互以及通过.idea目录管理运行配置。示例中的右键菜单与弹窗数据交互代码能够节省反复查阅官方文档的时间是入门IntelliJ IDEA插件开发的高性价比参考。1. 一份 IDEA 插件源码 Demo 的真实价值先跑通再读懂大多数人拿到“idea插件详细源码demo.zip”这个压缩包第一反应都是解压、导入、点运行看到弹窗出来就算学会了。但这类源码 Demo 真正值得学的从来不是那一个弹窗功能而是整套 IntelliJ 平台插件的运行骨架一个插件从action注册、service生命周期管理、listener事件监听到最后被 IDE 加载并响应用户操作每个环节的代码形态是怎样的。我接手过不少这种项目包也带过人从 Demo 复制扩展成正式功能所以这篇会按“环境搭建 → 配置解析 → 代码模块 → 翻车排查 → 进阶验证”的顺序把这类 Demo 里值得抄的东西摊开讲。它适合已经在写 Java、但对插件工程结构还不熟的开发者如果你只是想要一个“点一下弹提示框”的最小例子这份 Demo 往往高出这个需求不少但恰好能把你带过入门那道坎。2. 把 ZIP 变成可运行工程IDEA 插件环境搭建的三个关键动作2.1 解压之后先别急着导入确认语言、JDK 和 Gradle 版本IDEA 插件本质上不是独立应用它是构建在 IntelliJ 平台之上的一个模块最终要被平台加载进自己的进程运行。所以它的开发环境跟普通 Java 工程差别不小解压之后第一件事不是点绿色运行按钮而是先确认三件事。第一源码语言。现在的 Demo 工程两种语言都有纯 Java 或者 Kotlin。如果你只熟 Java拿到 Kotlin 的源码也能看懂但要复制代码时得留意空安全语法反过来也一样。我自己就吃过亏把一段 Kotlin 插件代码照搬到 Java 工程里结果整页编译报错最后发现是!!和?的差异跟插件逻辑一点关系都没有。第二JDK 版本。IntelliJ 平台对不同年代的产品线会用不同的编译目标插件工程里一般通过sourceCompatibility或 Project Structure 指定。不要只看本机装了哪个 JDK要看工程要求哪个版本。如果只装了 JDK 17、工程要求 11不用重装在 IDEA 的 Project Structure 里把两个 JDK 都配置好按模块切换就行。第三Gradle 版本。插件开发最通用的构建工具就是 Gradle一份完整的源码 Demo 通常自带gradle/wrapper。建议优先用 wrapper 里固定的版本跑不要图省事直接敲本机的gradle build。本机 Gradle 和插件模板要求的版本差太多经常会在 DSL 语法上报一些莫名其妙的错而这些问题其实跟代码本身没有关系。2.2 build.gradle 里四个最重要参数决定插件跑在哪个 IDE 上打开 Demo 的build.gradle你会看到类似下面的配置。这是最常见的接法之一我直接用一段可运行的 Groovy 版配置说明plugins { id java id org.jetbrains.intellij version 1.17.4 } group com.example version 1.0.0 repositories { mavenCentral() } intellij { version 2024.1 type IC plugins [com.intellij.java] } patchPluginXml { sinceBuild 231 untilBuild 241.* } runIde { ideDir file(/path/to/your/idea) } sourceCompatibility 17 targetCompatibility 17这里intellij块内四个参数要首先看懂。version是你要基于的 IntelliJ 平台版本号它决定你编译时能看到哪些类type是发行类型IC指社区版IU指旗舰版你要用到旗舰版专属功能时这里必须改plugins声明平台附加模块比如写 Java 相关的插件必须带上com.intellij.java否则一堆 Java 相关的类根本编译不到patchPluginXml里的sinceBuild和untilBuild则控制这个插件能被哪个版本区间的 IDE 加载后面第 5 章会重点讲它怎么坑人。runIde里的ideDir可有可无。不写的话Gradle 会下载对应的 IDE 沙箱写了的话就用你本机装好的 IDE 作为运行基座。我一般建议先把ideDir注释掉跑一次确认工程逻辑没问题之后再指到本地 IDE省掉下载环节。需要注意本机 IDE 的发行类型必须和type一致否则运行时的实际平台代码和编译期 SDK 会对不上这是非常隐蔽的问题。提示Demo 工程如果没带gradle/wrapper可以让 IDEA 的 Gradle 面板刷新后自动生成但注意把 wrapper 版本对齐到 Gradle 8 系否则容易找不到runIde任务。2.3 用 runIde 启动一个独立实例验证插件真的被加载配置完成之后最关键的一步是到 IDEA 右侧 Gradle 面板里找到intellij分组下的runIde任务双击运行。这一步会拉起一个全新的 IDE 实例这个实例里预先加载了你正在开发的插件。它跟你日常写代码的主 IDE 是两个独立进程所以不用担心把主 IDE 搞坏最坏结果就是把这个实验实例的配置弄乱。实例启动后从Help - Show Log in Files打开日志目录找idea.log搜索你的插件 ID。正常情况下能看到类似Plugin com.example.demo loaded的记录如果加载失败这里会直接给出失败原因比如找不到依赖模块、插件 XML 有解析错误或者 sinceBuild 不匹配。这个日志的信息量远大于盯着启动画面看半天。我习惯了每次改完代码都重新跑一次runIde因为插件改动的验证成本远比普通应用低不需要重新编译整个项目。还有一条路是装好 Plugin DevKit 之后在 Run 配置里添加“Plugin”运行方式。但通过 Gradle 跑的好处是它会自动把src/main/resources里的插件描述文件和源码按正确路径处理省去手工维护资源的环节。所以新工程建议直接走 Gradle 方案。2.4 标准源码 Demo 的目录布局帮你快速定位核心包demo-plugin/ ├── build.gradle ├── settings.gradle ├── gradle.properties ├── src/ │ ├── main/ │ │ ├── java/ │ │ │ └── com/example/demo/ │ │ │ ├── actions/ │ │ │ ├── services/ │ │ │ └── listeners/ │ │ └── resources/ │ │ ├── META-INF/ │ │ │ └── plugin.xml │ │ └── icons/ │ └── test/ │ └── java/ └── gradle/wrapper/大部分人拿到压缩包会直接打开plugin.xml我的建议是反过来先扫一遍src/main/java下的三个包目录基本能判断这份 Demo 展示了哪几种能力。actions里是菜单、工具栏入口services里是跨窗口复用的业务对象listeners里的代码负责把 IDE 内部事件接进你的逻辑。如果这几个目录只出现了一两个说明 Demo 侧重某一个功能复制代码时就不用把无关部分一起搬过去。3. plugin.xml 与源码是一体的先分清声明、扩展点和类的对应关系3.1 plugin.xml 不是普通配置文件它是插件的“入口清单”IDEA 插件启动时不会做反射扫描它能识别的一切能力都靠META-INF/plugin.xml声明出来。你在源码里写了AnAction子类但没在这个 XML 里注册IDE 永远不会知道这个类的存在。这也是初学者最容易误解的地方把插件当成普通 Java 工程觉得类写好了 IDE 就能自动找到实际上 plugin.xml 才是整个插件的入口。一个最小可跑的 plugin.xml 长这样idea-plugin idcom.example.demo/id nameDemo Plugin/name version1.0.0/version vendor emaildevexample.com urlhttps://example.comDemo Team/vendor dependscom.intellij.modules.platform/depends dependscom.intellij.java/depends applicationService serviceImplementationcom.example.demo.services.DemoSettingsService/ applicationListeners listener classcom.example.demo.listeners.MyDocumentListener topiccom.intellij.openapi.editor.event.EditorFactoryListener/ /applicationListeners actions action idcom.example.demo.ShowMessage classcom.example.demo.actions.ShowMessageAction textDemo: Show Message descriptionShow a message dialog add-to-group group-idToolsMenu anchorlast/ keyboard-shortcut keymap$default first-keystrokectrl alt shift D/ /action /actions /idea-plugin里面最核心的是三层结构。id是整个插件的唯一标识建议用反向域名depends声明依赖的平台模块如果不声明com.intellij.java却用了com.intellij.java里的类平台会在启动阶段直接拒绝这个插件而不是等运行到那行代码才报错actions、applicationService、applicationListeners则分别对应三类注册项它们是插件与 IDE 交互的窗口。vendor标签也不可忽视。本地调试时它没有任何作用但把插件打包分发给别人时IDE 会在插件的详情页展示这个信息在某些版本的 IDE 里缺失 vendor 信息会被安全机制标记为“不受信任的插件”。虽然是 Demo顺手写上总没坏处。3.2 动作注册三要素class 全限定名、菜单分组和快捷键actions块是整个 XML 里最好懂也最容易写错的部分。id全局唯一class必须和源码里的全限定类名完全一致add-to-group决定这个动作出现在哪个菜单。如果注册了action却没写add-to-group动作一样存在只是界面上没有任何入口只能通过快捷键或者代码调用。group-id写错时不会报编译错但启动日志会提示找不到目标组UI 里也找不到这个动作。这里有一个非常快的验证技巧在 IDE 的 Action 搜索框里输入你刚注册的动作text能搜到说明注册链路已经打通搜不到先回到 plugin.xml 查class是否存在再查group-id是否是真实存在的菜单组不要无头绪地改代码。keyboard-shortcut里的first-keystroke也值得注意。多个动作共用同一组快捷键时IDE 不会在编译期提示而是运行到触发时才弹冲突提示。源码 Demo 为了方便演示通常会挑一个很冷门的组合键比如ctrl alt shift D你自己扩展功能时沿用这个习惯对真实用户还算友好但发布前一定要检查快捷键冲突。3.3 用“从类到 XML”的反查法快速读懂陌生 Demo面对一个没见过的源码 Demo我最常用的方法是反查法先看某个类的包名比如com.example.demo.listeners.MyDocumentListener再回到plugin.xml里搜MyDocumentListener或listeners帮这个类定位它在插件体系里的角色。搜索命中位置决定了它是什么出现在actions里就是用户动作入口出现在applicationListeners里就是事件监听器如果整个 XML 里都搜不到那它大概率只是业务工具类由其他注册类在内部 new 出来用。操作上不用多复杂IDEA 自带Navigate - Search Everywhere搜类名再用右键Find Usages看谁引用了它。一个类被很多普通类引用但 plugin.xml 里完全没有它基本就是工具类只有被声明在 XML 里的类才承担与 IDE 交互的职责。这个判断能帮你快速划分边界哪些代码需要注册哪些代码不需要避免把整个项目的类全塞进 XML导致插件启动变慢甚至加载冲突。4. 源码 Demo 里最值得抄的三类代码块Action、Service、监听器4.1 一个最小可运行的 AnAction从点击到弹窗package com.example.demo.actions; import com.intellij.openapi.actionSystem.AnAction; import com.intellij.openapi.actionSystem.AnActionEvent; import com.intellij.openapi.ui.Messages; import org.jetbrains.annotations.NotNull; public class ShowMessageAction extends AnAction { Override public void actionPerformed(NotNull AnActionEvent e) { Messages.showInfoMessage( e.getProject(), Demo plugin is running., Demo Plugin ); } }AnActionEvent是动作触发时传入的上下文对象几乎所有 IDE 当前状态都能从它身上拿到当前项目e.getProject()、当前 PSI 文件e.getData(CommonDataKeys.PSI_FILE)、当前编辑器e.getData(CommonDataKeys.EDITOR)。要注意e.getProject()可能返回 null如果动作允许在没有项目的场景下触发比如从全局搜索入口触发就必须判空否则一按就空指针。这段代码只有一个actionPerformed也就是点击后的行为。但完整的动作类通常还会覆写一个update方法用来控制动作的可用状态Override public void update(NotNull AnActionEvent e) { PsiFile file e.getData(CommonDataKeys.PSI_FILE); e.getPresentation().setEnabled(file ! null file.getFileType().getName().equals(JAVA)); }update会在 IDE 认为状态可能变化时被高频调用所以这里千万不要做重操作比如读文件内容、解析大模型只能做轻量判断。很多新手把插件卡顿归咎于平台 SDK 慢实际是自己往update里塞了重型逻辑。4.2 用 PersistentStateComponent 实现用户配置记忆大多数插件终归要保存用户配置比如勾选状态、上次使用的路径。标准做法不是自己写文件而是实现PersistentStateComponent由平台管理生命周期配置自动写到 IDE 的配置目录你只需要定义好状态字段和 getter、setter。package com.example.demo.services; import com.intellij.openapi.components.PersistentStateComponent; import com.intellij.openapi.components.State; import com.intellij.openapi.components.Storage; import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.Nullable; State(name DemoSettings, storages {Storage(demo-plugin-settings.xml)}) public class DemoSettingsService implements PersistentStateComponentDemoSettingsService.State { public static class State { public boolean enableLivePreview true; public String lastUsedPath ; } private State myState new State(); Override public Nullable State getState() { return myState; } Override public void loadState(NotNull State state) { myState state; } public static DemoSettingsService getInstance() { return com.intellij.openapi.components.ServiceManager.getService(DemoSettingsService.class); } public boolean isEnableLivePreview() { return myState.enableLivePreview; } public void setEnableLivePreview(boolean val) { myState.enableLivePreview val; } }State里的name是存储 XML 里的根元素名可以自定义但最好保持全局唯一Storage指定存储文件名出现在 IDE 系统配置目录下。像demo-plugin-settings.xml这样带插件前缀的命名是最稳妥的否则容易和其他插件撞文件。getState和loadState是序列化和反序列化入口平台在配置变更时自动调用。getInstance()这段在比较新的平台版本里有更简洁的替代写法但用ServiceManager也还能跑Demo 里出现不必惊讶。关键是不要在 Service 构造器里做任何依赖 IDE 环境的初始化这一点第 5 章会单独展开。4.3 用 DocumentListener 监听文件变更文档事件与 PSI 的时序问题监听器是进阶 Demo 经常展示的能力因为它看起来“自动响应”但隐含的坑也最多。下面是一段监听编辑器文档行数变化的代码骨架package com.example.demo.listeners; import com.intellij.openapi.editor.EditorFactory; import com.intellij.openapi.editor.event.DocumentEvent; import com.intellij.openapi.editor.event.DocumentListener; import com.intellij.openapi.editor.Document; import com.intellij.openapi.diagnostic.Logger; import org.jetbrains.annotations.NotNull; public class LineCountListener { private static final Logger LOG Logger.getInstance(LineCountListener.class); public void install() { EditorFactory.getInstance().getEventMulticaster() .addDocumentListener(new DocumentListener() { Override public void documentChanged(NotNull DocumentEvent event) { Document doc event.getDocument(); handleChange(doc); } }, this); } private void handleChange(Document doc) { int lineCount doc.getLineCount(); LOG.info(Document changed, now lines lineCount); } }关键在addDocumentListener(listener, this)的第二个参数。它允许你传入一个 Disposable 或弱引用对象当这个对象被回收时监听器自动解除避免内存泄漏。很多年久失修的 Demo 会漏掉这个参数或者每次安装都 new 一个匿名对象注册结果就是文件一变就重复触发、内存持续膨胀最后 IDE 越来越慢。这是我在实际项目里见到的最高频的血泪经验。documentChanged里还有一条铁律不要直接在这个回调里触发 PSI 解析。文档变化事件发生的那一刻PSI 可能还是旧状态强行访问会拿到过期数据或者触发重解析。如果业务确实需要最新 PSI要用ApplicationManager.getApplication().invokeLater延迟到下一轮事件循环让平台先把 PSI 刷新完。注意监听器注册时要分清应用级和项目级。应用级监听写在applicationListeners项目级监听最好放在项目级 Service 的初始化逻辑里。如果把项目级监听注册成应用级所有打开的项目都会收到同一份事件造成跨项目状态污染排查起来非常隐蔽。5. 源码 Demo 复现中的避坑现场5 个高频翻车记录下面 5 条完全来自实际复现这类 Demo 时最容易卡住的点。每条按“现象 → 原因 → 解决”讲方便你直接对号入座。5.1 图标路径正确但按钮一片空白现象插件编译通过runIde 能启动动作也出现在菜单里但图标位置是空白方块打开资源目录resources/icons/foo.png明明存在XML 里路径似乎也对。原因最常见的是资源目录没有被打进最终的 jar。Gradle 下src/main/resources默认会打包但如果你把图片放在了src/main/java下面或者手工新建了resources目录却忘了在build.gradle里配置sourceSets就会漏打包。另一种情况是引用了 IDE 内置图标但 ID 写错结果就是空白。解决先把图片统一挪到src/main/resources/icons下XML 里用/icons/foo.png这种斜杠开头的写法。然后跑一次gradle build直接打开生成的 zip 检查对应路径是否存在这一步比在 IDE 里猜更直白。内置图标则去查图标 ID 表不要靠记忆硬写。5.2 插件被 IDE 禁用sinceBuild 和 untilBuild 版本范围没对上现象runIde 启动后插件根本没生效打开 Settings 的插件列表这个插件是灰色状态提示不兼容idea.log里能找到类似“since build”的数字。原因patchPluginXml里的sinceBuild、untilBuild与实际运行的 IDE 版本不在一条兼容线内。sinceBuild231表示只接受 2023.1 之后的 IDEuntilBuild241.*就表示 2024.1 之后不再支持。本地跑的 IDE 如果恰好超出范围插件直接被禁用。解决调试期把sinceBuild写低比如213untilBuild直接不填或者写很大的通配值保证沙箱 IDE 能加载。发布前再收窄范围否则用户在完全不同的 IDE 版本上装同一个插件运气好是功能失效运气差是启动崩溃比“不兼容”提示更难处理。5.3 启动即崩溃日志行号指向 Service 构造函数现象runIde 启动到一半弹出错误框idea.log里异常栈的行号指向某个 Service 的构造函数或者getInstance()调用处。原因多半是在 Service 初始化阶段做了不该做的事比如在构造函数里读取当前项目文件或者调用 UI 线程专属接口。IntelliJ 平台有自己的启动时序应用级 Service 构造时项目可能还没打开编辑器也没准备好你访问的一切都可能为 null 或抛异常。解决构造函数里只做纯字段和纯内存的初始化不碰项目、不碰文件、不碰编辑器。需要外部数据时放到第一次真正调用时再取或者在实现Disposable的初始化方法里做懒加载。如果 Demo 源码本身在构造函数里读文件照抄一定会翻车先重构再跑。5.4 改了代码但 runIde 里还是旧行为缓存和索引的锅现象改了一个字符串、删掉了一个 Action重新 runIde界面上还是旧内容。原因runIde 复用一个固定的沙箱目录里面继承着之前实验的 IDE 配置、缓存和索引。IDE 对自身缓存和第三方插件注册信息的更新有延迟尤其是动作注册这类信息被平台索引缓存下来时旧数据会长期残留。解决先在沙箱实例里执行File - Invalidate Caches / Restart把缓存清掉。还不行就更换沙箱目录或者手动删除系统临时目录里对应插件的缓存文件夹。这个问题原理不复杂但新手很容易误判断为代码没生效白白在代码里找半天根本不存在的 bug。5.5 编译期通过、运行期 ClassNotFound这不是玄学是平台版本不一致现象Gradle 编译没有任何报错runIde 启动后某个动作一触发就抛NoClassDefFoundError或ClassNotFoundException而且缺失的类看起来非常陌生。原因编译时用的 SDK 是intellij.version指定的版本但 runIde 实际使用的 IDE 来自本机安装目录或默认下载目录两个环境的 jar 集合不一致。某几个类在一个版本里有、另一个版本里没有于是编译期风平浪静运行期直接爆炸。很多新版本里才加入的 API 最容易触发这个问题。解决先核对intellij.version和运行环境的 IDE 版本把它们完全对齐把ideDir注释掉让 Gradle 下载标准版。插件开发里不存在“一次编译到处运行”的概念版本的把控全部体现在这一组配置上。源码 Demo 里常会附带一份推荐 IDE 版本别跳过那段说明。6. 在 Demo 之外再走一步用调试和回归验证让插件活得比 Demo 久调试插件比调试普通应用多一层概念runIde 实例和主 IDE 是两个进程但你可以用调试模式把主 IDE 挂到沙箱实例上。断点打在actionPerformed或documentChanged里在沙箱里触发操作主 IDE 就会命中断点。这是我最常用的验证手段比不停加日志高效。唯一要注意的是断点不要打进 IntelliJ 平台内部类里除非你已经定位到平台 bug否则会打断到怀疑人生。对源码 Demo 的扩展我建议给自己定一个回归检查清单功能入口是否还能打开菜单用户配置在重启 IDE 后是否还在文件变更后监听器是否只触发一次切换项目时有没有出现跨项目残留状态。这四个点看着简单却几乎能挡住插件开发里 80% 的回归事故。把 Demo 变成自己真正在维护的插件不是复制完代码就结束而是要回答四个问题类的生命周期归谁管、状态存到哪个存储文件、逻辑跑在哪个线程、依赖哪个版本的 IDE。前两个问题可以在 plugin.xml 和注解里找到答案后两个问题要靠实际运行验证。拿这份源码 Demo 练手时每一步都在回答这四个问题等它们不需要查代码就能答上来你对 IDEA 插件的理解就算真正过关了。我带人复现这类 Demo 时最后都会说一句话代码能跑通不是终点能定位第一次失败才是这套源码真正给你的东西。宁可花时间在小 Demo 里把排查链条走通也不要一开始就扑进大型插件工程。这是我踩过不少坑之后养成的习惯希望帮到你。本文还有配套的精品资源点击获取