产品兼容、模块与插件依赖¶

IntelliJ Platform 的插件兼容性不是只由 IDE 名称决定，而是由目标产品中实际存在的模块和插件决定。一个插件能否在 IDEA、PyCharm、WebStorm、GoLand、CLion、Rider 等产品中加载，核心取决于 plugin.xml 中声明的模块依赖和插件依赖是否能被满足。

兼容性判断模型¶

官方文档把依赖分为两类：

类型	例子	作用
平台模块	`com.intellij.modules.platform`、`com.intellij.modules.lang`	表示产品内置且不可移除的能力集合
插件依赖	`com.intellij.java`、`org.jetbrains.kotlin`、`JavaScript`	表示一个独立插件提供的 API 或功能

如果 plugin.xml 没有声明任何模块依赖，或只声明了其他插件依赖而没有模块依赖，平台会把它当成旧插件处理，这种写法已经不适合新项目。

所有新插件至少应声明：

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

如果插件使用语言能力，例如文件类型、Lexer、Parser、补全、重命名、格式化和导航，通常需要：

<depends>com.intellij.modules.lang</depends>

常用模块和插件¶

依赖 ID	提供能力	常见产品
`com.intellij.modules.platform`	消息总线、UI、文件、文档、Action、Service、Extension、Editor	所有独立 IDE
`com.intellij.modules.lang`	文件类型、语法、PSI、补全、导航、重构、格式化	所有独立 IDE
`com.intellij.modules.xml`	XML、DOM、XSD/DTD	多数 IDE
`com.intellij.modules.vcs`	VCS、变更列表、历史、注解	多数 IDE
`com.intellij.modules.xdebugger`	调试会话、断点、栈帧	支持调试的 IDE
`com.intellij.java` 或 `com.intellij.modules.java`	Java PSI、检查、补全、重构、测试框架	IDEA、Android Studio
`org.jetbrains.kotlin`	Kotlin 语言能力	安装 Kotlin 插件的 IDE
`JavaScript`	JavaScript/TypeScript 能力	WebStorm、IDEA Ultimate 等
`com.intellij.database`	数据库、SQL PSI、查询	DataGrip、IDEA Ultimate 等
`com.intellij.modules.python`	Python 语言能力	PyCharm、安装 Python 插件的 IDE

产品兼容性的经验规则：

只依赖 platform 或 lang 的插件更容易跨产品运行。
依赖 Java、Python、JavaScript、Database 等能力时，插件只会在这些能力存在的产品中可用。
Marketplace 会基于依赖自动推断产品兼容性，但发布前仍要用目标产品实际验证。
Remote Development 场景中，前端和后端的兼容性会分别判断。

三步声明插件依赖¶

官方依赖流程可以简化为三步。

1. 找到插件 ID¶

Marketplace 插件可以在详情页底部 Additional Information 中查看 Plugin ID。捆绑插件可以用 Gradle 任务列出：

./gradlew printBundledPlugins

或查看 IDE 安装目录中的插件描述文件：

$PRODUCT_ROOT$/plugins/$PLUGIN_NAME$/lib/$PLUGIN_NAME$.jar!/META-INF/plugin.xml

2. 在 Gradle 中加入依赖¶

dependencies {
    intellijPlatform {
        bundledPlugin("com.intellij.java")
        plugin("org.intellij.scala", "2024.1.4")
    }
}

规则：

捆绑插件使用 bundledPlugin()。
Marketplace 插件使用 plugin()。
普通第三方库仍然用标准 Gradle 依赖，例如 implementation()。

3. 在 plugin.xml 声明依赖¶

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

如果运行时报 NoClassDefFoundError，常见原因就是只配置了 Gradle 编译依赖，但忘记在 plugin.xml 里声明运行时插件依赖。

可选依赖¶

当插件只在某个宿主插件存在时启用额外能力，使用可选依赖：

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

额外描述符放在同一目录：

<idea-plugin>
  <extensions defaultExtensionNs="com.intellij">
    <annotator language="kotlin" implementationClass="com.example.MyKotlinAnnotator"/>
  </extensions>
</idea-plugin>

命名建议使用 myPluginId-$NAME$.xml，避免测试和类加载器中出现同名描述符冲突。

不兼容声明¶

如果插件明确不能在包含某模块的产品中运行，可以用：

<incompatible-with>com.intellij.modules.someModule</incompatible-with>

这不是常规兼容性控制手段。多数情况下应通过精确的 <depends> 声明表达需要的能力。

验证依赖¶

发布前至少验证：

plugin.xml 中包含 com.intellij.modules.platform 或更具体模块。
Gradle 依赖和 plugin.xml 依赖一致。
目标产品能启动插件，不只是在 IDEA 中能启动。
verifyPlugin 或 runPluginVerifier 覆盖目标 IDE 构建。
若目标多产品，分别运行对应 IDE 的开发实例或 Plugin Verifier。