在实际开发中我们经常遇到一些重复性的编码任务比如生成特定格式的代码、快速创建项目骨架、或者集成某个固定的工具链。手动处理这些任务不仅耗时而且容易出错。如果你使用 IntelliJ IDEA 或 Visual Studio Code 这类现代 IDE一个高效的解决方案就是自己动手编写插件。本文将以“Vibe Coding”为灵感带你从零开始在 IntelliJ IDEA 中创建一个能够提升编码“氛围感”和效率的实用插件。我们将从理解插件的基本结构开始一步步完成开发、调试、打包和安装的全过程并解释其中的关键机制和常见陷阱。无论你是想为团队定制开发规范检查工具还是想将个人常用的代码片段自动化掌握插件开发技能都能让你对 IDE 有更深的理解并显著提升工作效率。本文将假设你具备 Java 基础并使用 IntelliJ IDEA 作为开发环境。最终你将得到一个可以实际运行的最小插件并了解如何在此基础上扩展功能。1. 理解 IntelliJ Platform 插件的基本概念在动手写代码之前需要先理解 IntelliJ Platform 插件是什么以及它是如何工作的。这能帮助你避免在后续开发中陷入“为什么我的代码不生效”的困惑。1.1 插件是什么它能做什么一个 IntelliJ Platform 插件本质上是一个遵循特定规范的 JAR 包它被 IDE 在启动时或运行时动态加载。插件可以扩展 IDE 的核心功能其能力范围非常广泛用户界面UI添加新的菜单项、工具栏按钮、工具窗口如 Project 窗口侧边栏、对话框。代码操作提供代码补全、语法高亮、错误检查Inspections、快速修复Quick Fixes、重构Refactorings。项目模型与项目、模块、文件系统进行交互监听文件变化。外部工具集成集成命令行工具、构建系统如 Gradle、Maven、版本控制系统如 Git。简单来说几乎所有你在 IntelliJ IDEA 里看到和使用的非核心功能都可能是一个插件。自己开发插件就是按照平台的约定编写代码来“告诉”IDE 在何时何地执行我们定义的操作。1.2 核心工作机制扩展点Extension Point与扩展Extension这是 IntelliJ Platform 插件架构的核心模式是一种典型的控制反转IoC设计。扩展点Extension Point由 IDE 平台或其它插件定义的一种“插座”或“接口”。它声明了在某个特定场景下例如“需要创建一个动作”或“需要提供一个代码补全器”平台可以接受外部插件的贡献。扩展点通常有明确的接口或基类。扩展Extension由我们的插件实现的“插头”。我们编写一个类来实现扩展点定义的接口或继承其基类然后将这个类注册到对应的扩展点上。当 IDE 运行到相关场景时就会自动发现并调用我们注册的扩展实现。例如平台定义了一个叫做com.intellij.openapi.actionSystem.AnAction的扩展点实际上是一个基类用于表示一个用户界面动作。我们的插件可以创建一个继承自AnAction的类并实现其actionPerformed方法。然后在插件的配置文件中将这个类注册到该扩展点下。当用户点击我们插件添加的菜单按钮时IDE 就会实例化我们的类并调用actionPerformed方法。1.3 插件描述文件plugin.xml这是插件的“身份证”和“说明书”是一个 XML 文件必须放在插件的META-INF目录下。它包含了插件的元信息和对扩展点的声明。元信息插件 ID、名称、版本、描述、供应商、依赖的 IDE 版本、依赖的其它插件等。扩展声明通过extensions标签声明插件向哪些扩展点提供了实现。动作声明通过actions标签声明插件添加了哪些用户动作如菜单项、工具栏按钮并将其与具体的AnAction实现类关联。理解了这个模型后续的配置和编码就会清晰很多我们大部分工作就是在实现具体的扩展类并在plugin.xml中正确注册它们。2. 搭建插件开发环境与创建第一个项目开发 IntelliJ 插件需要使用 IntelliJ IDEA 本身并且推荐使用 Gradle 作为构建工具因为它能很好地处理依赖管理和打包任务。2.1 环境准备与前置检查在开始前请确保你的环境满足以下要求组件要求检查命令/方式JDK必须使用 JetBrains Runtime (JBR) 或与目标 IDE 版本匹配的 JDK 11/17。使用不匹配的 JDK 是编译失败的最常见原因。File-Project Structure-SDK。建议从 IDEA 安装目录下的jbr目录添加 SDK。IntelliJ IDEA社区版Community或旗舰版Ultimate均可。版本建议使用较新的稳定版。关于对话框查看版本。Gradle通常由 IDEA 内置或包装器Wrapper管理无需单独安装。项目创建时会自动配置。注意开发插件的 JDK 版本强烈建议与你要兼容的 IDE 所基于的 JDK 版本一致。例如开发兼容 IDEA 2022.3 的插件应使用 JDK 17。使用错误的 JDK 会导致Unsupported class file major version错误。2.2 使用官方模板创建插件项目IntelliJ IDEA 提供了创建插件项目的专用模板这是最可靠的方式。启动 IDEA点击New Project。在左侧类别中选择IntelliJ Platform Plugin。在右侧Project SDK一项至关重要。点击下拉框如果列表中没有合适的 JDKJBR 11/17点击Add JDK...导航到你的 IDEA 安装目录选择jbr文件夹对于 macOS可能在Contents下的jbr目录。然后选择这个新添加的 JDK。为项目命名例如MyVibeCodingPlugin选择项目存储位置。在Additional Libraries and Frameworks部分确保Gradle被选中并且语言选择Java。Kotlin也可选但本文以 Java 为例。点击Create。项目创建完成后Gradle 会自动开始构建和下载依赖。观察底部的Build工具窗口等待构建成功。2.3 解析初始项目结构创建完成后项目结构如下所示MyVibeCodingPlugin/ ├── build.gradle.kts // Gradle 构建脚本定义依赖、打包配置 ├── settings.gradle.kts // Gradle 设置文件 ├── gradle/ │ └── wrapper/ // Gradle 包装器保证构建环境一致 ├── src/ │ └── main/ │ ├── java/ // Java 源代码目录 │ ├── resources/ // 资源文件目录 │ │ └── META-INF/ │ │ └── plugin.xml // 插件核心描述文件 │ └── kotlin/ // Kotlin 源代码目录如果创建时选择了 Kotlin └── .run/ // 运行配置目录关键文件说明build.gradle.kts 需要重点关注。它定义了插件依赖的 IntelliJ Platform SDK 版本、插件兼容的 IDE 版本范围、以及打包配置。src/main/resources/META-INF/plugin.xml 插件的核心配置文件。初始内容包含了插件的基本信息和一些示例扩展点声明。打开build.gradle.kts你会看到类似以下内容plugins { id(java) id(org.jetbrains.intellij) version 1.17.3 // IntelliJ 插件 Gradle 插件 } group com.yourcompany version 1.0-SNAPSHOT repositories { mavenCentral() } // 配置 IntelliJ 插件扩展 intellij { version.set(2023.3.5) // 目标 IDE 版本 type.set(IC) // IC: Community Edition, IU: Ultimate Edition plugins.set(listOf(/* 可添加依赖的插件如 com.intellij.java */)) } tasks { patchPluginXml { sinceBuild.set(231) // 插件兼容的起始构建版本 untilBuild.set(233.*) // 插件兼容的结束构建版本 } signPlugin { certificateChain.set(System.getenv(CERTIFICATE_CHAIN)) privateKey.set(System.getenv(PRIVATE_KEY)) password.set(System.getenv(PRIVATE_KEY_PASSWORD)) } publishPlugin { token.set(System.getenv(PUBLISH_TOKEN)) } }你需要根据实际情况调整version你的插件版本、intellij.version用于开发的 IDE 版本以及sinceBuild/untilBuild兼容性范围。3. 实现一个简单的动作Action插件我们将从一个最简单的功能开始添加一个菜单项当用户点击时在编辑器中选择的文本前后添加特定的“氛围”标记例如✨并显示一个通知。3.1 创建自定义 Action 类在src/main/java下创建你的包路径例如com.yourcompany.vibecoding。在该包下新建一个 Java 类命名为AddVibeAction。让这个类继承com.intellij.openapi.actionSystem.AnAction。package com.yourcompany.vibecoding; import com.intellij.openapi.actionSystem.AnAction; import com.intellij.openapi.actionSystem.AnActionEvent; import com.intellij.openapi.actionSystem.CommonDataKeys; import com.intellij.openapi.command.WriteCommandAction; import com.intellij.openapi.editor.Caret; import com.intellij.openapi.editor.Document; import com.intellij.openapi.editor.Editor; import com.intellij.openapi.project.Project; import com.intellij.openapi.ui.Messages; import org.jetbrains.annotations.NotNull; public class AddVibeAction extends AnAction { Override public void actionPerformed(NotNull AnActionEvent e) { // 1. 获取当前项目和编辑器 final Project project e.getProject(); final Editor editor e.getData(CommonDataKeys.EDITOR); if (editor null || project null) { // 如果没有活动的编辑器或项目不执行任何操作 return; } // 2. 获取当前文档和主光标选择区域 final Document document editor.getDocument(); final Caret primaryCaret editor.getCaretModel().getPrimaryCaret(); // 3. 获取选中的文本 String selectedText primaryCaret.getSelectedText(); if (selectedText null || selectedText.isEmpty()) { Messages.showInfoMessage(project, 请先选择一些文本。, 提示); return; } // 4. 计算选中文本的起始和结束偏移量 int start primaryCaret.getSelectionStart(); int end primaryCaret.getSelectionEnd(); // 5. 在写操作中修改文档这是线程安全的要求 WriteCommandAction.runWriteCommandAction(project, () - { // 构造新的文本内容 String newText ✨ selectedText ✨; // 替换选中区域的文本 document.replaceString(start, end, newText); }); // 6. 移除选择区域将光标定位到新文本末尾 primaryCaret.removeSelection(); // 7. 显示一个简单的完成通知可选 Messages.showInfoMessage(project, 已为选中文本添加 Vibe 标记, 操作完成); } /** * 根据上下文更新 Action 的可用状态可选但推荐。 * 例如只有在有编辑器且有选中文本时才启用此 Action。 */ Override public void update(NotNull AnActionEvent e) { final Project project e.getProject(); final Editor editor e.getData(CommonDataKeys.EDITOR); // 设置 Action 的显示状态仅在项目和编辑器存在且有文本被选中时可用 e.getPresentation().setEnabledAndVisible( project ! null editor ! null editor.getSelectionModel().hasSelection() ); } }代码关键点解释actionPerformed 用户触发动作时调用的核心方法。所有 UI 操作都应在此处理。CommonDataKeys.EDITOR/PROJECT 用于从事件中获取当前的编辑器或项目对象。这是与 IDE 交互的入口。WriteCommandAction.runWriteCommandAction非常重要。任何修改文档Document的操作都必须在写命令中执行这是 IntelliJ Platform 保证 undo/redo 功能正常工作以及线程安全的要求。update 这个方法在 UI 显示前被调用例如每次打开菜单时。我们可以在这里根据上下文是否有项目、是否有选中文本来动态设置动作是否可用setEnabled或是否显示setVisible。实现它可以提供更好的用户体验。3.2 在 plugin.xml 中注册 Action仅仅有 Action 类还不够我们需要告诉 IDE 这个动作的存在以及它应该出现在哪里。这需要在plugin.xml中配置。打开src/main/resources/META-INF/plugin.xml。初始文件里可能有一些示例配置我们可以修改或添加自己的配置。idea-plugin !-- 插件唯一标识通常使用反向域名 -- idcom.yourcompany.vibecoding.plugin/id !-- 插件名称显示在插件市场和管理界面 -- nameMy Vibe Coding Plugin/name !-- 供应商信息 -- vendor emailsupportyourcompany.com urlhttps://www.yourcompany.comYour Company/vendor !-- 插件描述 -- description![CDATA[ A simple plugin to add some vibe to your selected code.br Select text and use the action to wrap it with sparkles. ]]/description !-- 依赖声明 -- dependscom.intellij.modules.platform/depends !-- 如果插件功能依赖 Java 语言支持可以添加 -- !-- dependscom.intellij.java/depends -- !-- 扩展点声明 -- extensions defaultExtensionNscom.intellij !-- 未来可以在这里添加其他扩展如工具窗口、服务等 -- /extensions !-- 动作声明 -- actions !-- 将我们的 Action 添加到 EditorPopupMenu (右键菜单) 和 ToolsMenu (主工具菜单) -- action idVibeCoding.AddVibeAction classcom.yourcompany.vibecoding.AddVibeAction textAdd Vibe _Mark descriptionWrap selected text with sparkles. !-- 添加到编辑器右键菜单 -- add-to-group group-idEditorPopupMenu anchorfirst/ !-- 添加到主菜单的 Tools 菜单下 -- add-to-group group-idToolsMenu anchorlast/ !-- 可以添加快捷键此处示例为 AltV需要更多配置 -- !-- keyboard-shortcut keymap$default first-keystrokealt V/ -- /action /actions /idea-plugin配置关键点解释action标签 定义了一个动作。id 动作的唯一标识符。class 对应的 Action 实现类的全限定名。text 显示在菜单或按钮上的文本。_后面的字母表示助记符如_Mark中的 M。description 鼠标悬停时的提示文本。add-to-group标签 指定将这个动作添加到哪个 UI 组菜单/工具栏以及位置。group-id 目标组的 ID如EditorPopupMenu编辑器右键菜单、ToolsMenu顶部菜单栏的 Tools 菜单。anchor 位置可以是first、last或相对于其他动作的 ID如afterSomeOtherActionId。4. 运行、调试与打包插件4.1 在沙盒中运行插件IntelliJ Platform 插件开发最方便的一点是可以在一个独立的沙盒 IDE 实例中运行和调试你的插件。在 Gradle 工具窗口通常在右侧展开Tasks-intellij。双击runIde任务。或者你也可以点击主工具栏附近的运行配置下拉菜单选择Run Plugin如果已自动生成。Gradle 会开始构建插件并启动一个新的 IDEA 实例沙盒。这个新实例安装了你的插件。在新打开的沙盒 IDEA 中创建一个新项目或打开一个现有项目。在代码编辑器中选中一段文本。右键点击你应该能在右键菜单的顶部看到Add Vibe Mark选项。点击它选中的文本前后应该会被添加✨符号。你也可以在顶部菜单栏的Tools菜单底部找到同样的选项。4.2 调试插件调试和运行一样简单在runIde任务上右键选择Debug ‘MyVibeCodingPlugin [runIde]’或直接点击调试按钮。沙盒 IDEA 会以调试模式启动。在你的插件代码如AddVibeAction.java中设置断点。在沙盒中触发你的动作如点击菜单调试器就会在你的主 IDEA 中暂停你可以查看变量、单步执行等。4.3 打包插件为 JAR 文件当你完成开发并希望分享或安装插件时需要将其打包。在 Gradle 工具窗口中双击Tasks-intellij-buildPlugin。任务执行成功后会在build/distributions/目录下生成一个 ZIP 文件例如MyVibeCodingPlugin-1.0-SNAPSHOT.zip。这个 ZIP 文件包含了插件 JAR 和所有依赖。这个 ZIP 文件就是可以分发的插件包。要安装到本地 IDEA打开 IDEA进入File-Settings(Windows/Linux) 或IntelliJ IDEA-Preferences(macOS)。选择Plugins-⚙️-Install Plugin from Disk...。选择刚才生成的 ZIP 文件重启 IDEA 即可。5. 进阶功能与常见问题排查一个简单的动作插件只是开始。你可以基于此探索更多强大的扩展点。5.1 探索其他扩展点工具窗口ToolWindow 创建像 Project、Run 那样的侧边栏窗口。扩展点com.intellij.toolWindow。代码检查Inspection 实现自定义的代码静态分析规则。扩展点com.intellij.inspection。代码补全Completion Contributor 提供自定义的代码补全建议。扩展点com.intellij.completion.contributor。文件类型关联 为你自定义的文件类型提供语法高亮、图标等。需要实现FileType并注册。服务Service 创建插件级别的单例服务用于管理状态或提供全局功能。通过Service注解或applicationService/projectService扩展点注册。5.2 常见问题与排查清单在插件开发过程中你可能会遇到以下问题问题现象可能原因检查与解决步骤插件运行后菜单项不显示或不可用1.plugin.xml中动作注册的class路径错误。2.update方法逻辑错误将动作设为了不可见或不可用。3. 动作被添加到了不存在的group-id。1. 检查plugin.xml中action class...的值是否与 Java 类的全限定名完全一致。2. 在update方法开始处添加日志或断点检查传入的AnActionEvent中的project和editor是否不为 null。3. 查阅官方文档确认使用的group-id是否正确。点击菜单项无反应或报错1.actionPerformed方法中有未处理的异常。2. 修改文档未在WriteCommandAction中执行。3. 插件依赖缺失或版本冲突。1. 查看沙盒 IDEA 的日志文件Help - Show Log in Explorer/Finder。2.确保所有对Document的insert/replace/delete操作都包裹在WriteCommandAction.runWriteCommandAction中。3. 检查build.gradle.kts中的intellij.plugins依赖是否正确添加。构建失败提示Unsupported class file major version项目使用的 JDK 版本高于或低于目标 IDE 支持的版本。1. 检查File - Project Structure - Project SDK确保使用的是 JBR 11 或 17。2. 检查build.gradle.kts中的intellij.version确保其对应的 IDE 版本与你使用的 JDK 匹配。插件在沙盒中运行正常打包后安装失败或功能异常1. 打包时未包含依赖。2.plugin.xml中sinceBuild/untilBuild版本范围与安装的 IDE 不兼容。3. 资源文件未正确打包。1. 使用buildPlugin任务打包它会自动处理依赖。不要手动打包 JAR。2. 检查plugin.xml中的版本范围或查看build.gradle.kts中patchPluginXml任务的配置。3. 确保资源文件位于src/main/resources的正确子目录下。无法调试断点不生效1. 未以调试模式运行。2. 源代码与沙盒中加载的类版本不一致。1. 确认点击的是Debug按钮而不是Run。2. 尝试Build - Rebuild Project然后重新Debug。5.3 开发与调试最佳实践充分利用官方文档和源码 JetBrains 的 IntelliJ Platform SDK Docs 是首要参考资料。对于不熟悉的类直接查看其源码在 IDEA 中 CtrlClick是理解其用法的最快方式。从简单案例开始 在实现复杂功能前先创建一个最小可运行的 Action确保你的基础环境、注册和事件响应流程是正确的。善用日志 在actionPerformed或update方法中使用Logger.getInstance(YourClass.class).info/debug/warn(...)输出日志在沙盒的Help - Show Log中查看这是排查运行时逻辑问题的关键。注意线程安全 UI 操作如显示对话框必须在事件分发线程EDT上执行而长时间运行的任务应放在后台线程。修改文档必须使用WriteCommandAction。测试不同版本兼容性 在build.gradle.kts中合理设置sinceBuild和untilBuild。如果使用新版本的 API需要确保插件声明了最低兼容版本。管理插件状态 如果插件需要保存用户设置使用PersistentStateComponent来存储配置。对于项目级或应用级的单例服务使用Service注解。通过以上步骤你已经完成了一个完整 IntelliJ Platform 插件的开发闭环。从理解扩展点机制到创建项目、实现功能、注册配置、运行调试再到打包分发和问题排查。这个为选中文本添加装饰的“Vibe Coding”插件虽然简单但它包含了插件开发最核心的流程。你可以以此为起点参考官方文档探索更多强大的扩展点逐步构建出能够真正融入你或团队工作流、提升编码体验和效率的个性化工具。
在实际开发中我们经常遇到一些重复性的编码任务比如生成特定格式的代码、快速创建项目骨架、或者集成某个固定的工具链。手动处理这些任务不仅耗时而且容易出错。如果你使用 IntelliJ IDEA 或 Visual Studio Code 这类现代 IDE一个高效的解决方案就是自己动手编写插件。本文将以“Vibe Coding”为灵感带你从零开始在 IntelliJ IDEA 中创建一个能够提升编码“氛围感”和效率的实用插件。我们将从理解插件的基本结构开始一步步完成开发、调试、打包和安装的全过程并解释其中的关键机制和常见陷阱。无论你是想为团队定制开发规范检查工具还是想将个人常用的代码片段自动化掌握插件开发技能都能让你对 IDE 有更深的理解并显著提升工作效率。本文将假设你具备 Java 基础并使用 IntelliJ IDEA 作为开发环境。最终你将得到一个可以实际运行的最小插件并了解如何在此基础上扩展功能。1. 理解 IntelliJ Platform 插件的基本概念在动手写代码之前需要先理解 IntelliJ Platform 插件是什么以及它是如何工作的。这能帮助你避免在后续开发中陷入“为什么我的代码不生效”的困惑。1.1 插件是什么它能做什么一个 IntelliJ Platform 插件本质上是一个遵循特定规范的 JAR 包它被 IDE 在启动时或运行时动态加载。插件可以扩展 IDE 的核心功能其能力范围非常广泛用户界面UI添加新的菜单项、工具栏按钮、工具窗口如 Project 窗口侧边栏、对话框。代码操作提供代码补全、语法高亮、错误检查Inspections、快速修复Quick Fixes、重构Refactorings。项目模型与项目、模块、文件系统进行交互监听文件变化。外部工具集成集成命令行工具、构建系统如 Gradle、Maven、版本控制系统如 Git。简单来说几乎所有你在 IntelliJ IDEA 里看到和使用的非核心功能都可能是一个插件。自己开发插件就是按照平台的约定编写代码来“告诉”IDE 在何时何地执行我们定义的操作。1.2 核心工作机制扩展点Extension Point与扩展Extension这是 IntelliJ Platform 插件架构的核心模式是一种典型的控制反转IoC设计。扩展点Extension Point由 IDE 平台或其它插件定义的一种“插座”或“接口”。它声明了在某个特定场景下例如“需要创建一个动作”或“需要提供一个代码补全器”平台可以接受外部插件的贡献。扩展点通常有明确的接口或基类。扩展Extension由我们的插件实现的“插头”。我们编写一个类来实现扩展点定义的接口或继承其基类然后将这个类注册到对应的扩展点上。当 IDE 运行到相关场景时就会自动发现并调用我们注册的扩展实现。例如平台定义了一个叫做com.intellij.openapi.actionSystem.AnAction的扩展点实际上是一个基类用于表示一个用户界面动作。我们的插件可以创建一个继承自AnAction的类并实现其actionPerformed方法。然后在插件的配置文件中将这个类注册到该扩展点下。当用户点击我们插件添加的菜单按钮时IDE 就会实例化我们的类并调用actionPerformed方法。1.3 插件描述文件plugin.xml这是插件的“身份证”和“说明书”是一个 XML 文件必须放在插件的META-INF目录下。它包含了插件的元信息和对扩展点的声明。元信息插件 ID、名称、版本、描述、供应商、依赖的 IDE 版本、依赖的其它插件等。扩展声明通过extensions标签声明插件向哪些扩展点提供了实现。动作声明通过actions标签声明插件添加了哪些用户动作如菜单项、工具栏按钮并将其与具体的AnAction实现类关联。理解了这个模型后续的配置和编码就会清晰很多我们大部分工作就是在实现具体的扩展类并在plugin.xml中正确注册它们。2. 搭建插件开发环境与创建第一个项目开发 IntelliJ 插件需要使用 IntelliJ IDEA 本身并且推荐使用 Gradle 作为构建工具因为它能很好地处理依赖管理和打包任务。2.1 环境准备与前置检查在开始前请确保你的环境满足以下要求组件要求检查命令/方式JDK必须使用 JetBrains Runtime (JBR) 或与目标 IDE 版本匹配的 JDK 11/17。使用不匹配的 JDK 是编译失败的最常见原因。File-Project Structure-SDK。建议从 IDEA 安装目录下的jbr目录添加 SDK。IntelliJ IDEA社区版Community或旗舰版Ultimate均可。版本建议使用较新的稳定版。关于对话框查看版本。Gradle通常由 IDEA 内置或包装器Wrapper管理无需单独安装。项目创建时会自动配置。注意开发插件的 JDK 版本强烈建议与你要兼容的 IDE 所基于的 JDK 版本一致。例如开发兼容 IDEA 2022.3 的插件应使用 JDK 17。使用错误的 JDK 会导致Unsupported class file major version错误。2.2 使用官方模板创建插件项目IntelliJ IDEA 提供了创建插件项目的专用模板这是最可靠的方式。启动 IDEA点击New Project。在左侧类别中选择IntelliJ Platform Plugin。在右侧Project SDK一项至关重要。点击下拉框如果列表中没有合适的 JDKJBR 11/17点击Add JDK...导航到你的 IDEA 安装目录选择jbr文件夹对于 macOS可能在Contents下的jbr目录。然后选择这个新添加的 JDK。为项目命名例如MyVibeCodingPlugin选择项目存储位置。在Additional Libraries and Frameworks部分确保Gradle被选中并且语言选择Java。Kotlin也可选但本文以 Java 为例。点击Create。项目创建完成后Gradle 会自动开始构建和下载依赖。观察底部的Build工具窗口等待构建成功。2.3 解析初始项目结构创建完成后项目结构如下所示MyVibeCodingPlugin/ ├── build.gradle.kts // Gradle 构建脚本定义依赖、打包配置 ├── settings.gradle.kts // Gradle 设置文件 ├── gradle/ │ └── wrapper/ // Gradle 包装器保证构建环境一致 ├── src/ │ └── main/ │ ├── java/ // Java 源代码目录 │ ├── resources/ // 资源文件目录 │ │ └── META-INF/ │ │ └── plugin.xml // 插件核心描述文件 │ └── kotlin/ // Kotlin 源代码目录如果创建时选择了 Kotlin └── .run/ // 运行配置目录关键文件说明build.gradle.kts 需要重点关注。它定义了插件依赖的 IntelliJ Platform SDK 版本、插件兼容的 IDE 版本范围、以及打包配置。src/main/resources/META-INF/plugin.xml 插件的核心配置文件。初始内容包含了插件的基本信息和一些示例扩展点声明。打开build.gradle.kts你会看到类似以下内容plugins { id(java) id(org.jetbrains.intellij) version 1.17.3 // IntelliJ 插件 Gradle 插件 } group com.yourcompany version 1.0-SNAPSHOT repositories { mavenCentral() } // 配置 IntelliJ 插件扩展 intellij { version.set(2023.3.5) // 目标 IDE 版本 type.set(IC) // IC: Community Edition, IU: Ultimate Edition plugins.set(listOf(/* 可添加依赖的插件如 com.intellij.java */)) } tasks { patchPluginXml { sinceBuild.set(231) // 插件兼容的起始构建版本 untilBuild.set(233.*) // 插件兼容的结束构建版本 } signPlugin { certificateChain.set(System.getenv(CERTIFICATE_CHAIN)) privateKey.set(System.getenv(PRIVATE_KEY)) password.set(System.getenv(PRIVATE_KEY_PASSWORD)) } publishPlugin { token.set(System.getenv(PUBLISH_TOKEN)) } }你需要根据实际情况调整version你的插件版本、intellij.version用于开发的 IDE 版本以及sinceBuild/untilBuild兼容性范围。3. 实现一个简单的动作Action插件我们将从一个最简单的功能开始添加一个菜单项当用户点击时在编辑器中选择的文本前后添加特定的“氛围”标记例如✨并显示一个通知。3.1 创建自定义 Action 类在src/main/java下创建你的包路径例如com.yourcompany.vibecoding。在该包下新建一个 Java 类命名为AddVibeAction。让这个类继承com.intellij.openapi.actionSystem.AnAction。package com.yourcompany.vibecoding; import com.intellij.openapi.actionSystem.AnAction; import com.intellij.openapi.actionSystem.AnActionEvent; import com.intellij.openapi.actionSystem.CommonDataKeys; import com.intellij.openapi.command.WriteCommandAction; import com.intellij.openapi.editor.Caret; import com.intellij.openapi.editor.Document; import com.intellij.openapi.editor.Editor; import com.intellij.openapi.project.Project; import com.intellij.openapi.ui.Messages; import org.jetbrains.annotations.NotNull; public class AddVibeAction extends AnAction { Override public void actionPerformed(NotNull AnActionEvent e) { // 1. 获取当前项目和编辑器 final Project project e.getProject(); final Editor editor e.getData(CommonDataKeys.EDITOR); if (editor null || project null) { // 如果没有活动的编辑器或项目不执行任何操作 return; } // 2. 获取当前文档和主光标选择区域 final Document document editor.getDocument(); final Caret primaryCaret editor.getCaretModel().getPrimaryCaret(); // 3. 获取选中的文本 String selectedText primaryCaret.getSelectedText(); if (selectedText null || selectedText.isEmpty()) { Messages.showInfoMessage(project, 请先选择一些文本。, 提示); return; } // 4. 计算选中文本的起始和结束偏移量 int start primaryCaret.getSelectionStart(); int end primaryCaret.getSelectionEnd(); // 5. 在写操作中修改文档这是线程安全的要求 WriteCommandAction.runWriteCommandAction(project, () - { // 构造新的文本内容 String newText ✨ selectedText ✨; // 替换选中区域的文本 document.replaceString(start, end, newText); }); // 6. 移除选择区域将光标定位到新文本末尾 primaryCaret.removeSelection(); // 7. 显示一个简单的完成通知可选 Messages.showInfoMessage(project, 已为选中文本添加 Vibe 标记, 操作完成); } /** * 根据上下文更新 Action 的可用状态可选但推荐。 * 例如只有在有编辑器且有选中文本时才启用此 Action。 */ Override public void update(NotNull AnActionEvent e) { final Project project e.getProject(); final Editor editor e.getData(CommonDataKeys.EDITOR); // 设置 Action 的显示状态仅在项目和编辑器存在且有文本被选中时可用 e.getPresentation().setEnabledAndVisible( project ! null editor ! null editor.getSelectionModel().hasSelection() ); } }代码关键点解释actionPerformed 用户触发动作时调用的核心方法。所有 UI 操作都应在此处理。CommonDataKeys.EDITOR/PROJECT 用于从事件中获取当前的编辑器或项目对象。这是与 IDE 交互的入口。WriteCommandAction.runWriteCommandAction非常重要。任何修改文档Document的操作都必须在写命令中执行这是 IntelliJ Platform 保证 undo/redo 功能正常工作以及线程安全的要求。update 这个方法在 UI 显示前被调用例如每次打开菜单时。我们可以在这里根据上下文是否有项目、是否有选中文本来动态设置动作是否可用setEnabled或是否显示setVisible。实现它可以提供更好的用户体验。3.2 在 plugin.xml 中注册 Action仅仅有 Action 类还不够我们需要告诉 IDE 这个动作的存在以及它应该出现在哪里。这需要在plugin.xml中配置。打开src/main/resources/META-INF/plugin.xml。初始文件里可能有一些示例配置我们可以修改或添加自己的配置。idea-plugin !-- 插件唯一标识通常使用反向域名 -- idcom.yourcompany.vibecoding.plugin/id !-- 插件名称显示在插件市场和管理界面 -- nameMy Vibe Coding Plugin/name !-- 供应商信息 -- vendor emailsupportyourcompany.com urlhttps://www.yourcompany.comYour Company/vendor !-- 插件描述 -- description![CDATA[ A simple plugin to add some vibe to your selected code.br Select text and use the action to wrap it with sparkles. ]]/description !-- 依赖声明 -- dependscom.intellij.modules.platform/depends !-- 如果插件功能依赖 Java 语言支持可以添加 -- !-- dependscom.intellij.java/depends -- !-- 扩展点声明 -- extensions defaultExtensionNscom.intellij !-- 未来可以在这里添加其他扩展如工具窗口、服务等 -- /extensions !-- 动作声明 -- actions !-- 将我们的 Action 添加到 EditorPopupMenu (右键菜单) 和 ToolsMenu (主工具菜单) -- action idVibeCoding.AddVibeAction classcom.yourcompany.vibecoding.AddVibeAction textAdd Vibe _Mark descriptionWrap selected text with sparkles. !-- 添加到编辑器右键菜单 -- add-to-group group-idEditorPopupMenu anchorfirst/ !-- 添加到主菜单的 Tools 菜单下 -- add-to-group group-idToolsMenu anchorlast/ !-- 可以添加快捷键此处示例为 AltV需要更多配置 -- !-- keyboard-shortcut keymap$default first-keystrokealt V/ -- /action /actions /idea-plugin配置关键点解释action标签 定义了一个动作。id 动作的唯一标识符。class 对应的 Action 实现类的全限定名。text 显示在菜单或按钮上的文本。_后面的字母表示助记符如_Mark中的 M。description 鼠标悬停时的提示文本。add-to-group标签 指定将这个动作添加到哪个 UI 组菜单/工具栏以及位置。group-id 目标组的 ID如EditorPopupMenu编辑器右键菜单、ToolsMenu顶部菜单栏的 Tools 菜单。anchor 位置可以是first、last或相对于其他动作的 ID如afterSomeOtherActionId。4. 运行、调试与打包插件4.1 在沙盒中运行插件IntelliJ Platform 插件开发最方便的一点是可以在一个独立的沙盒 IDE 实例中运行和调试你的插件。在 Gradle 工具窗口通常在右侧展开Tasks-intellij。双击runIde任务。或者你也可以点击主工具栏附近的运行配置下拉菜单选择Run Plugin如果已自动生成。Gradle 会开始构建插件并启动一个新的 IDEA 实例沙盒。这个新实例安装了你的插件。在新打开的沙盒 IDEA 中创建一个新项目或打开一个现有项目。在代码编辑器中选中一段文本。右键点击你应该能在右键菜单的顶部看到Add Vibe Mark选项。点击它选中的文本前后应该会被添加✨符号。你也可以在顶部菜单栏的Tools菜单底部找到同样的选项。4.2 调试插件调试和运行一样简单在runIde任务上右键选择Debug ‘MyVibeCodingPlugin [runIde]’或直接点击调试按钮。沙盒 IDEA 会以调试模式启动。在你的插件代码如AddVibeAction.java中设置断点。在沙盒中触发你的动作如点击菜单调试器就会在你的主 IDEA 中暂停你可以查看变量、单步执行等。4.3 打包插件为 JAR 文件当你完成开发并希望分享或安装插件时需要将其打包。在 Gradle 工具窗口中双击Tasks-intellij-buildPlugin。任务执行成功后会在build/distributions/目录下生成一个 ZIP 文件例如MyVibeCodingPlugin-1.0-SNAPSHOT.zip。这个 ZIP 文件包含了插件 JAR 和所有依赖。这个 ZIP 文件就是可以分发的插件包。要安装到本地 IDEA打开 IDEA进入File-Settings(Windows/Linux) 或IntelliJ IDEA-Preferences(macOS)。选择Plugins-⚙️-Install Plugin from Disk...。选择刚才生成的 ZIP 文件重启 IDEA 即可。5. 进阶功能与常见问题排查一个简单的动作插件只是开始。你可以基于此探索更多强大的扩展点。5.1 探索其他扩展点工具窗口ToolWindow 创建像 Project、Run 那样的侧边栏窗口。扩展点com.intellij.toolWindow。代码检查Inspection 实现自定义的代码静态分析规则。扩展点com.intellij.inspection。代码补全Completion Contributor 提供自定义的代码补全建议。扩展点com.intellij.completion.contributor。文件类型关联 为你自定义的文件类型提供语法高亮、图标等。需要实现FileType并注册。服务Service 创建插件级别的单例服务用于管理状态或提供全局功能。通过Service注解或applicationService/projectService扩展点注册。5.2 常见问题与排查清单在插件开发过程中你可能会遇到以下问题问题现象可能原因检查与解决步骤插件运行后菜单项不显示或不可用1.plugin.xml中动作注册的class路径错误。2.update方法逻辑错误将动作设为了不可见或不可用。3. 动作被添加到了不存在的group-id。1. 检查plugin.xml中action class...的值是否与 Java 类的全限定名完全一致。2. 在update方法开始处添加日志或断点检查传入的AnActionEvent中的project和editor是否不为 null。3. 查阅官方文档确认使用的group-id是否正确。点击菜单项无反应或报错1.actionPerformed方法中有未处理的异常。2. 修改文档未在WriteCommandAction中执行。3. 插件依赖缺失或版本冲突。1. 查看沙盒 IDEA 的日志文件Help - Show Log in Explorer/Finder。2.确保所有对Document的insert/replace/delete操作都包裹在WriteCommandAction.runWriteCommandAction中。3. 检查build.gradle.kts中的intellij.plugins依赖是否正确添加。构建失败提示Unsupported class file major version项目使用的 JDK 版本高于或低于目标 IDE 支持的版本。1. 检查File - Project Structure - Project SDK确保使用的是 JBR 11 或 17。2. 检查build.gradle.kts中的intellij.version确保其对应的 IDE 版本与你使用的 JDK 匹配。插件在沙盒中运行正常打包后安装失败或功能异常1. 打包时未包含依赖。2.plugin.xml中sinceBuild/untilBuild版本范围与安装的 IDE 不兼容。3. 资源文件未正确打包。1. 使用buildPlugin任务打包它会自动处理依赖。不要手动打包 JAR。2. 检查plugin.xml中的版本范围或查看build.gradle.kts中patchPluginXml任务的配置。3. 确保资源文件位于src/main/resources的正确子目录下。无法调试断点不生效1. 未以调试模式运行。2. 源代码与沙盒中加载的类版本不一致。1. 确认点击的是Debug按钮而不是Run。2. 尝试Build - Rebuild Project然后重新Debug。5.3 开发与调试最佳实践充分利用官方文档和源码 JetBrains 的 IntelliJ Platform SDK Docs 是首要参考资料。对于不熟悉的类直接查看其源码在 IDEA 中 CtrlClick是理解其用法的最快方式。从简单案例开始 在实现复杂功能前先创建一个最小可运行的 Action确保你的基础环境、注册和事件响应流程是正确的。善用日志 在actionPerformed或update方法中使用Logger.getInstance(YourClass.class).info/debug/warn(...)输出日志在沙盒的Help - Show Log中查看这是排查运行时逻辑问题的关键。注意线程安全 UI 操作如显示对话框必须在事件分发线程EDT上执行而长时间运行的任务应放在后台线程。修改文档必须使用WriteCommandAction。测试不同版本兼容性 在build.gradle.kts中合理设置sinceBuild和untilBuild。如果使用新版本的 API需要确保插件声明了最低兼容版本。管理插件状态 如果插件需要保存用户设置使用PersistentStateComponent来存储配置。对于项目级或应用级的单例服务使用Service注解。通过以上步骤你已经完成了一个完整 IntelliJ Platform 插件的开发闭环。从理解扩展点机制到创建项目、实现功能、注册配置、运行调试再到打包分发和问题排查。这个为选中文本添加装饰的“Vibe Coding”插件虽然简单但它包含了插件开发最核心的流程。你可以以此为起点参考官方文档探索更多强大的扩展点逐步构建出能够真正融入你或团队工作流、提升编码体验和效率的个性化工具。
