跳转至

产品专属 API 与多 IDE 支持

JetBrains IDE 共用 IntelliJ Platform，但每个产品携带的模块和捆绑插件不同。多 IDE 插件的关键不是“在 IDEA 能跑”，而是准确声明依赖、隔离产品专属代码、在目标产品中验证。

依赖决定产品兼容性

Marketplace 和 IDE 加载插件时，会根据 plugin.xml 的模块和插件依赖判断兼容产品。

基础依赖：

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

语言和产品能力依赖示例：

<depends>com.intellij.modules.lang</depends>
<depends>com.intellij.java</depends>
<depends optional="true" config-file="with-javascript.xml">JavaScript</depends>
<depends optional="true" config-file="with-database.xml">com.intellij.database</depends>

Gradle 也要声明对应依赖：

dependencies {
    intellijPlatform {
        bundledPlugin("com.intellij.java")
        bundledPlugin("JavaScript")
        bundledPlugin("com.intellij.database")
    }
}

常见产品能力

能力 依赖 ID 常见产品
Java com.intellij.java / com.intellij.modules.java IDEA、Android Studio
Kotlin org.jetbrains.kotlin 安装 Kotlin 插件的 IDE
JavaScript / TypeScript JavaScript WebStorm、IDEA Ultimate 等
Database / SQL com.intellij.database DataGrip、IDEA Ultimate 等
Python com.intellij.modules.python PyCharm、安装 Python 插件的 IDE
PHP com.jetbrains.php PhpStorm
Go org.jetbrains.plugins.go GoLand
VCS com.intellij.modules.vcs 多数 IDE
Debugger com.intellij.modules.xdebugger 支持调试的 IDE

官方兼容表不是穷尽列表。实际项目中，plugin.xml 的 <depends> 补全、目标 IDE 的 bundled plugins 列表和 Plugin Verifier 更可靠。

可选依赖隔离

跨产品插件应把产品专属扩展拆到可选描述符：

<depends optional="true" config-file="myPlugin-withJavaScript.xml">JavaScript</depends>

myPlugin-withJavaScript.xml：

<idea-plugin>
  <extensions defaultExtensionNs="com.intellij">
    <completion.contributor
        language="JavaScript"
        implementationClass="com.example.js.ExampleJsCompletionContributor"/>
  </extensions>
</idea-plugin>

这样 WebStorm/IDEA Ultimate 有 JS 能力时加载 JS 功能，没有 JS 插件的产品仍能加载主插件。

代码隔离策略

策略 适用场景
可选 plugin.xml 描述符 扩展点注册依赖某插件
单独 package/module 产品专属代码较多
Service facade 主逻辑需要调用可选能力
反射或 extension lookup 少量软依赖，且有清晰降级路径
多模块 split 复杂插件，按能力和运行侧拆分

不要在主插件初始化路径直接引用可选插件类，否则即使 XML 是可选依赖，也可能在类加载时失败。

验证矩阵

最低矩阵应包含：

  • 最低支持 IDE build。
  • 最新稳定 IDE build。
  • 每个宣称支持的产品至少一个版本。
  • 缺少可选依赖的产品。
  • 安装了可选依赖的产品。

验证方式：

./gradlew verifyPlugin
./gradlew runPluginVerifier

并且至少手动在对应 IDE 开发实例或本地安装包中验证一次关键功能。只跑 IDEA 不足以证明 PyCharm/WebStorm/DataGrip 兼容。

产品 API 升级风险

产品插件 API 比平台核心更容易变化。近年常见变化包括：

  • Java plugin 拆分模块。
  • WebSymbols 改名为 PolySymbols。
  • Database 旧 UI/API 移除。
  • JavaScript/TypeScript Stub Element 类型调整。
  • 外部系统接口变化。

实践建议：

  • 避免依赖 impl、internal 包。
  • 对产品专属 API 单独建测试。
  • 升级目标平台时先读 Incompatible Changes。
  • 对可选依赖功能加 feature flag 或优雅降级。
  • 把产品专属代码集中，降低迁移影响面。

参考来源