简介这是一份面向IntelliJ IDEA插件开发初学者与进阶者的详细源码示例围绕插件结构、事件监听、Action系统、Dialog与Popup交互以及Swing组件应用等核心知识点展开帮助开发者在较短时间内理解IDE扩展机制并上手实践。压缩包共16个文件约10KB以java源码与xml配置为主辅以svg图标、iml模块文件及gitignore等工程辅助文件分别承载插件逻辑实现、组件注册、界面资源与项目配置等职责目录组织清晰便于按模块研读。目前已有785人学习下载。通过研究该demo读者可掌握菜单项注册、鼠标右键数据交互、弹出框定制等常见交互功能的实现思路理解项目配置文件与资源管理方式并借助内置工具完成插件的测试与调试从而系统提升插件开发能力。1. 从一份能跑通的 IDEA 插件源码说起菜单、弹窗、右键交互到底怎么串起来很多人第一次写 IntelliJ IDEA 插件卡住的地方不是 Java 语法而是不知道一个 Action 从注册到被点击、再到弹出对话框中间到底经过哪些文件。这份ideaPluginProject源码 demo 的价值就在这它把「相关菜单」「弹出框」「鼠标右键数据交互」这三类最常见的交互入口用一份能直接导入 IDE 的工程串了起来。你拿到的是一个标准 Gradle/IDEA 插件工程结构src下是业务代码resources/META-INF下是plugin.xml和两套图标.idea与.iml负责工程识别。适合已经会写 Java、想快速把插件跑起来的人也适合想搞清楚plugin.xml里每个标签到底管什么的人。下面按「结构 → 注册 → 交互 → 排错 → 进阶」的顺序拆每一步都能对着源码复现。2. 工程结构与 plugin.xml插件能被 IDE 认出来的最小闭环2.1 目录里每个文件到底管什么先把压缩包解开对照下面这张表看能省掉大量「这个文件能不能删」的犹豫。路径作用能不能动src/Java 源码Action、Dialog、工具类都在这核心随便改resources/META-INF/plugin.xml插件描述文件注册 Action、依赖、版本核心改错直接不加载resources/META-INF/pluginIcon.svg亮色主题图标可替换resources/META-INF/pluginIcon_dark.svg暗色主题图标可替换ideaPluginProject.iml模块配置声明 SDK 和依赖一般不动.idea/工作区配置含 artifacts、modules不建议手改.idea/artifacts/ideaPluginProject_jar.xml打包产物定义打包相关谨慎plugin.xml是整个插件的入口清单。IDE 启动时扫描这个文件把里面声明的 Action、扩展点挂到对应位置。源码里pluginIcon.svg和pluginIcon_dark.svg成对出现是因为新版 IDE 会根据主题自动切换只放一个在暗色主题下会显示异常这是很多人第一次提交插件时被审核打回的原因。2.2 一个 Action 从声明到可点击插件里「相关菜单」和「右键菜单」本质都是 Action。区别只在注册时挂到哪个group。看下面这段典型注册!-- resources/META-INF/plugin.xml -- idea-plugin idcom.rcc.ideaPluginProject/id nameIdeaPluginDemo/name vendorrcc/vendor dependscom.intellij.modules.platform/depends actions !-- 挂到主菜单 Tools 下 -- action idcom.rcc.demo.HelloAction classcom.rcc.action.HelloAction textSay Hello description弹出问候对话框 add-to-group group-idToolsMenu anchorfirst/ keyboard-shortcut keymap$default first-keystrokectrl alt H/ /action !-- 挂到编辑器右键菜单 -- action idcom.rcc.demo.RightClickAction classcom.rcc.action.RightClickAction textProcess Selection description处理选中的文本 add-to-group group-idEditorPopupMenu anchorlast/ /action /actions /idea-pluginid必须全局唯一建议用包名倒序class指向继承AnAction的实现类add-to-group决定它出现在哪ToolsMenu是顶部 Tools 菜单EditorPopupMenu就是编辑器里右键弹出的那一层。anchor控制插入位置first/last最省事。keyboard-shortcut里的$default表示默认键位方案写死keymap名在别人机器上可能不生效。提示改完plugin.xml一定要重新加载插件或重启沙箱 IDE热部署对 Action 注册不生效这是最常见的「我明明改了却没反应」。2.3 用沙箱把插件跑起来IDEA 插件开发不需要你装一个独立 IDE它自带沙箱运行配置。操作路径是打开工程 → 右侧 Gradle 面板 →Tasks intellij runIde或者直接点运行配置里的Run Plugin。第一次会下载一个对应版本的 IDE 沙箱耐心等。# 命令行方式等价于点 runIde ./gradlew runIde # 只编译不启动沙箱用来快速验证语法 ./gradlew buildPluginrunIde会拉起一个全新的 IDE 实例你注册的菜单和右键项只在这个沙箱里出现不会污染你日常用的 IDE。buildPlugin产出的是可分发的 zip在build/distributions下。判断插件是否被正确加载看沙箱 IDE 启动日志里有没有你的插件名没有就是plugin.xml写错了。3. 菜单、弹窗与右键数据交互三类交互的代码落地3.1 AnAction 里拿到当前上下文Action 被点击时actionPerformed会收到一个AnActionEvent所有上下文都从它身上取。下面是一个能拿到当前编辑器、选中文本、当前项目的完整写法public class RightClickAction extends AnAction { Override public void actionPerformed(NotNull AnActionEvent e) { // 当前项目可能为 null比如欢迎页触发 Project project e.getProject(); // 当前编辑器右键菜单里一般不为 null Editor editor e.getData(CommonDataKeys.EDITOR); if (project null || editor null) { return; } // 选中的文本 String selected editor.getSelectionModel().getSelectedText(); if (selected null || selected.isEmpty()) { Messages.showInfoMessage(project, 没有选中任何文本, 提示); return; } // 处理选中内容 String result selected.toUpperCase(); Messages.showInfoMessage(project, 处理结果 result, 完成); } Override public void update(NotNull AnActionEvent e) { // 控制菜单项是否可点、是否可见 Editor editor e.getData(CommonDataKeys.EDITOR); boolean hasSelection editor ! null editor.getSelectionModel().hasSelection(); e.getPresentation().setEnabledAndVisible(hasSelection); } }actionPerformed是点击后的逻辑update是每次菜单弹出前调用的用来决定这一项灰不灰、显不显。很多人只写actionPerformed结果没选中文本时菜单项也能点点完报空指针这就是漏了update。CommonDataKeys.EDITOR是取编辑器的标准姿势别去用FileEditorManager绕一圈右键场景下前者更直接。3.2 自定义 Dialog 与 Popup 的选型「弹出框」在 IDEA 插件里有两套东西别混。DialogWrapper是模态对话框适合要用户填表单、点确定的场景JBPopupFactory是轻量气泡适合展示信息或做快速选择。源码 demo 里两种都有涉及选型看交互重量。public class MyDialog extends DialogWrapper { private final JTextField input new JTextField(20); protected MyDialog(Project project) { super(project); setTitle(输入内容); init(); // 必须调用否则界面不显示 } Override protected JComponent createCenterPanel() { JPanel panel new JPanel(new BorderLayout()); panel.add(new JLabel(请输入), BorderLayout.WEST); panel.add(input, BorderLayout.CENTER); return panel; } public String getInput() { return input.getText(); } }DialogWrapper的坑集中在init()不调用它createCenterPanel返回的界面根本不会渲染你会得到一个空白窗口还找不到原因。createCenterPanel只负责中间区域按钮区由基类自动生成想改按钮文案重写createActions。// 轻量气泡适合展示结果 JBPopupFactory.getInstance() .createHtmlTextBalloonBuilder(b处理完成/b, MessageType.INFO, null) .setFadeoutTime(3000) .createBalloon() .show(RelativePoint.getCenterOf(editor.getComponent()), Balloon.Position.above);气泡用createHtmlTextBalloonBuildersetFadeoutTime控制自动消失毫秒数show的锚点用编辑器组件中心位置比硬编码坐标稳。模态对话框会阻塞用户操作气泡不会展示类信息优先用气泡。3.3 右键菜单的数据回传右键交互的完整链路是用户在编辑器选中文本 → 右键 → 点你的菜单项 → Action 拿到选中内容 → 处理 → 结果回显。回显有两种常见做法一是上面用的Messages.showInfoMessage二是把结果写回编辑器或弹出自定义 Dialog。// 把处理结果替换回编辑器 WriteCommandAction.runWriteCommandAction(project, () - { Document doc editor.getDocument(); doc.replaceString( editor.getSelectionModel().getSelectionStart(), editor.getSelectionModel().getSelectionEnd(), result ); });写回编辑器必须包在WriteCommandAction里直接改Document会抛AssertionError这是 IDEA 的写保护机制不是 bug。replaceString的起止位置从SelectionModel取别自己算偏移量多光标场景下会算错。4. 避坑与排查插件加载失败、Action 不显示、沙箱报错4.1 插件在沙箱里根本没加载现象runIde起来了但菜单里找不到你的项日志也没有插件名。原因通常是plugin.xml的id与build.gradle里的pluginGroup不一致或者depends写了一个沙箱版本不支持的模块。解决把id改成和pluginGroup完全一致depends先用com.intellij.modules.platform这个最基础的确认能加载后再加别的。4.2 Action 显示了但一直是灰的现象菜单项能看到但点不动。原因基本都在update方法里setEnabledAndVisible传了false或者取Editor时用了错误的DataKey。解决在update里打日志确认editor是否为 null右键场景用CommonDataKeys.EDITOR主菜单场景可能取不到编辑器要改用e.getData(CommonDataKeys.PROJECT)判断。4.3 图标在暗色主题下看不见现象亮色主题正常切到暗色主题图标变黑块或消失。原因是只提供了pluginIcon.svg没提供pluginIcon_dark.svg或者两个文件内容一样但颜色写死。解决两个文件都放暗色版用浅色描边plugin.xml里不用额外声明IDE 按文件名自动匹配。4.4 改 Document 抛 AssertionError现象右键处理完想把结果写回编辑器控制台报AssertionError: Must not change document outside command。原因是没包WriteCommandAction。解决所有对Document的写操作都套一层WriteCommandAction.runWriteCommandAction(project, () - {...})这是硬性要求。4.5 沙箱启动卡在下载现象第一次runIde长时间停在下载 IDE 沙箱。原因是默认下载源慢或版本号写得太具体。解决在build.gradle里把intellij { version.set(2023.1) }换成一个你本地已装的大版本或者用localPath指向本地 IDE 安装目录跳过下载。5. 进阶把 demo 改成自己的插件并验证打包产物5.1 从 demo 派生一个新插件的最小改动集拿到这份源码后别急着大改先做最小改动验证链路通不通。改三处plugin.xml里的id、name、vendorbuild.gradle里的pluginGroup和versionsrc下包名com.rcc重构成你自己的。改完跑一次runIde确认沙箱里插件名变了、菜单项还在说明派生成功。这一步不做后面出问题你分不清是 demo 本身的问题还是你改出来的问题。5.2 打包产物怎么验证./gradlew buildPlugin之后产物在build/distributions/下是一个 zip。验证方法不是解压看而是直接拿沙箱 IDE 的「从磁盘安装插件」功能装这个 zip重启后看功能是否正常。这一步能暴露很多runIde阶段发现不了的问题比如资源文件没被打进去、plugin.xml里的路径大小写不一致。# 打包 ./gradlew buildPlugin # 查看产物内容确认 plugin.xml 和图标都在 unzip -l build/distributions/*.zip | grep -E plugin.xml|pluginIconunzip -l列出压缩包内容重点确认META-INF/plugin.xml和两个图标在不在。资源文件缺失是打包阶段最常见的翻车点runIde时资源从源码目录读打包后从 jar 里读路径处理稍有不同就会丢。5.3 一个我每次都会走的验证习惯插件开发最坑的地方在于「沙箱里好好的装到正式 IDE 就崩」。我现在的习惯是任何一次改动先runIde验证交互再buildPlugin打包最后把 zip 装进一个干净的 IDE 实例跑一遍核心功能。三步都过才算完成少一步都可能把问题带到用户那边。这份 demo 的结构足够干净适合拿来当这个流程的起点——把它的 Action 换成你自己的逻辑把 Dialog 换成你的表单右键链路原样保留基本不会在框架层面踩坑。希望这份拆解帮到你少走几次「明明能跑却装不上」的弯路。本文还有配套的精品资源点击获取