plugin.xml 配置文件¶

plugin.xml 是插件的描述符。IDE 通过它读取插件元数据、兼容版本、依赖关系、扩展点、Action、监听器和服务声明。

文件通常位于：

src/main/resources/META-INF/plugin.xml

最小结构¶

<idea-plugin>
  <id>com.example.myplugin</id>
  <name>My Plugin</name>
  <vendor email="dev@example.com" url="https://example.com">Example</vendor>

  <description><![CDATA[
    <p>Provides useful IDE features for Example projects.</p>
  ]]></description>

  <depends>com.intellij.modules.platform</depends>
</idea-plugin>

核心元素¶

元素	作用	建议
`id`	插件技术标识	发布后不要改；使用反向域名风格
`name`	用户看到的插件名	简短、清晰、Title Case
`version`	插件版本	可由 Gradle `patchPluginXml` 注入
`vendor`	作者或组织	Marketplace 展示用
`description`	插件介绍	支持简单 HTML，通常放在 CDATA 中
`change-notes`	版本变更说明	发布新版本时更新
`depends`	依赖模块或插件	平台、Java、Kotlin、数据库等能力都要明确声明
`extensions`	注册扩展	大部分 IDE 能力通过扩展点接入
`actions`	注册 Action	菜单、工具栏、快捷入口

依赖声明¶

平台模块依赖示例：

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

可选依赖适合跨 IDE 或跨语言插件：

<depends optional="true" config-file="with-kotlin.xml">org.jetbrains.kotlin</depends>

当 Kotlin 插件存在时，IDE 会加载 with-kotlin.xml 中的额外扩展；不存在时，主插件仍可加载。

注册扩展¶

<extensions defaultExtensionNs="com.intellij">
  <applicationService serviceImplementation="com.example.MyAppService"/>
  <projectService serviceImplementation="com.example.MyProjectService"/>
  <completion.contributor
      language="JAVA"
      implementationClass="com.example.MyCompletionContributor"/>
</extensions>

如果 defaultExtensionNs="com.intellij"，可以省略扩展点名前缀。否则需要写完整扩展点名。

注册 Action¶

<actions>
  <action
      id="com.example.myplugin.ShowInfoAction"
      class="com.example.myplugin.ShowInfoAction"
      text="Show Project Info"
      description="Show information about the current project">
    <add-to-group group-id="ToolsMenu" anchor="first"/>
  </action>
</actions>

Action 的 id 必须唯一。一个实现类可以注册成多个 Action，但每个注册项都要有不同 ID。

额外配置文件¶

大型插件可以拆分配置文件：

<xi:include href="/META-INF/my-plugin-actions.xml"/>

可选依赖也常配合额外配置文件使用。这样可以避免在缺少某个宿主插件时加载相关扩展导致失败。

常见坑¶

不要使用官方未文档化的 XML 元素或属性，它们通常是 JetBrains 内部用途。
id、name、version、description 可以由 Gradle 插件补丁注入，但源码中仍建议保留关键元数据，方便阅读。
依赖了 Java/Kotlin/Python 等语言 API，就要同时在 Gradle 与 plugin.xml 声明。
对用户可见的文字建议放到资源包中，便于国际化。

参考来源¶

Plugin Configuration File