requires plugin 'com.intellij.modules.ultimate' to be installed

Question

在开发 IntelliJ IDEA 插件时，常遇到错误提示“requires plugin 'com.intellij.modules.ultimate' to be installed”。该问题出现在插件声明中依赖了仅限 Ultimate 版本的功能模块（如 Java 支持、Web 开发工具等），但目标运行环境为 Community Edition。Community 版不包含这些专有模块，导致插件无法加载。常见于自定义语言支持或框架集成插件误引用了 Ultimate 专属 API。解决方法包括：改为依赖通用模块（如 com.intellij.modules.platform）、使用可选依赖（），或明确声明仅支持 Ultimate 版。需在 plugin.xml 中谨慎配置依赖以确保兼容性。

Answer 1

IntelliJ IDEA 插件开发中“requires plugin 'com.intellij.modules.ultimate'”错误深度解析

1. 问题背景与表层现象

在开发 IntelliJ IDEA 插件时，开发者常遇到如下错误提示：

Error: Plugin "MyPlugin" requires plugin 'com.intellij.modules.ultimate' to be installed.

该错误通常出现在启动 Community Edition（社区版）IDEA 时，插件无法加载。其直接原因是插件的 plugin.xml 文件中声明了对 com.intellij.modules.ultimate 的依赖，而该模块仅存在于 Ultimate Edition（旗舰版）中。

社区版作为开源免费版本，不包含 Java EE、Spring、Web、数据库工具等高级功能模块，因此无法满足此类依赖。

2. 深层机制：IntelliJ 平台模块系统架构

IntelliJ IDEA 基于模块化平台设计，不同功能被划分为独立的模块（Module），通过 <depends> 标签在 plugin.xml 中声明依赖关系。

关键模块包括：

• com.intellij.modules.platform：基础平台模块，所有插件均可依赖，包含 UI、编辑器核心、项目模型等。
• com.intellij.modules.lang：语言支持基础，适用于自定义语言插件。
• com.intellij.modules.java：Java 语言支持，仅限 Ultimate 版本可用。
• com.intellij.modules.ultimate：标识插件仅运行于 Ultimate 版本。

当插件间接或直接引用了 Java PSI、Spring Context、Web Facet 等 API 时，Gradle 或 Maven 构建系统可能自动引入这些专有模块依赖，导致兼容性断裂。

3. 常见误用场景分析

场景	触发原因	典型API引用
自定义框架集成插件	调用 SpringFacet 或 WebModuleConfiguration	com.intellij.spring.facet.SpringFacet
DSL语言插件	继承 JavaParserDefinition	com.intellij.lang.java.JavaLanguage
代码生成工具	使用 JavaDirectoryService	com.intellij.psi.impl.PsiDirectoryFactory
项目向导插件	依赖 Java Module Type	JavaModuleType

4. 解决方案全景图

1. 替换为通用平台模块依赖
2. 使用可选依赖（optional dependency）机制
3. 条件化代码执行（Class.forName + try-catch）
4. 明确声明仅支持 Ultimate 版本
5. 利用 ServiceLocator 模式动态加载功能

5. 实践方案一：依赖重构为 platform 模块

修改 plugin.xml 中的依赖声明：

<!-- 错误写法 -->
<depends>com.intellij.modules.ultimate</depends>

<!-- 正确写法：使用通用平台模块 -->
<depends optional="true" config-file="my-plugin-java.xml">
  com.intellij.modules.java
</depends>

<!-- 基础依赖应始终存在 -->
<depends>com.intellij.modules.platform</depends>

通过将专有模块设为 optional="true"，并指定独立的配置文件，可实现功能按需加载。

6. 实践方案二：可选依赖与功能降级策略

在插件主类中判断运行环境：

public class MyPluginComponent {
    public void initComponent() {
        if (isUltimateAvailable()) {
            registerJavaExtensions();
        } else {
            registerBasicExtensions();
        }
    }

    private boolean isUltimateAvailable() {
        try {
            Class.forName("com.intellij.spring.contexts.model.SpringFacet");
            return true;
        } catch (ClassNotFoundException e) {
            return false;
        }
    }
}

7. 架构设计建议：插件分层模型

graph TD A[Core Layer] -->|Provides base services| B(Platform Module Only) C[Java Extension Layer] -->|Extends core| D(Optional: com.intellij.modules.java) E[Web Extension Layer] -->|Adds web features| F(Optional: com.intellij.modules.web) B --> G[Deployable Plugin Bundle] D --> G F --> G

采用分层架构，将核心功能与扩展功能解耦，提升跨版本兼容性。

8. 构建与测试最佳实践

• 在 build.gradle 中配置多个 IDE 版本进行测试：

intellij {
    version = 'IC-2023.2' // Community Edition
    type = 'IC'
}
test {
    jvmArgs "-Didea.plugins.compatible.build.number=232.*"
}

• 使用 IntelliJ Platform Explorer 工具分析 API 所属模块。
• 持续集成中并行测试 IC 与 IU 构建。

9. 社区生态与长期维护考量

超过 60% 的开源插件选择兼容 Community Edition，以扩大用户基础。但涉及企业级框架（如 Spring Boot、Kubernetes YAML）时，往往需牺牲部分功能以换取兼容性。

建议在插件市场描述中明确标注：

Compatibility:
- ✅ IntelliJ IDEA Community Edition (Basic Features)
- ✅ IntelliJ IDEA Ultimate (Full Feature Set)

10. 高级技巧：动态服务注册与 SPI 机制

通过 META-INF/services 实现运行时功能探测：

// file: META-INF/services/com.intellij.openapi.extensions.PluginExtensionPoint
my.plugin.JavaSupportExtension

结合 ServiceManager.getService() 与 ExtensionPointName 动态注册，实现优雅的功能启用与禁用。