开发实例、调试与兼容性验证¶
插件开发的基本反馈环路是：运行开发实例、触发插件功能、查看日志、修复问题、运行测试和兼容性验证。这个环路越稳定，后续开发成本越低。
开发实例¶
Gradle 项目使用：
./gradlew runIde
它会启动目标 IDE 的开发实例，并把当前插件安装到沙盒环境。开发实例和你日常使用的 IDE 配置隔离，因此适合反复调试插件加载、卸载、设置页和 Marketplace 安装包。
默认沙盒目录：
build/$TARGET_IDE$/idea-sandbox
沙盒中通常包含：
| 目录 | 内容 |
|---|---|
config |
开发实例设置 |
plugins |
安装到开发实例的插件 |
system 或缓存目录 |
日志、索引、缓存 |
遇到无法复现或状态污染时，优先清理沙盒再试，而不是马上怀疑代码。
JetBrains Runtime¶
开发实例应使用 JetBrains Runtime，因为 JetBrains IDE 依赖 JBR 中的修复和桌面能力。IntelliJ Platform Gradle Plugin 2.x 默认会为开发实例获取与目标平台匹配的 JBR。
需要指定时，可配置 runIde 的 JBR 版本。不要简单地把“构建插件的 JDK”和“运行 IDE 的 Runtime”混为一谈。
Auto-Reload¶
IntelliJ Platform Gradle Plugin 2.x 默认启用 Auto-Reload。通常流程：
- 启动
runIde。 - 修改插件代码。
- 运行
buildPlugin。 - 切回开发实例触发插件重载。
注意：
- 调试器附加时 Auto-Reload 不工作。
- 只有符合动态插件限制的插件才能可靠重载。
- 卸载失败时，生产环境会要求用户重启 IDE。
禁用自动重载：
intellijPlatform.autoReload=false
日志与排错¶
常用入口：
- 开发实例菜单：
Help | Show Log in Finder/Explorer。 - Gradle 输出：
runIde、buildPlugin、verifyPlugin。 - IDE 内部模式与 Plugin DevKit 检查。
idea.log中的插件 ID、异常栈、PluginException。
错误归因建议：
- 自己处理扩展实现异常时，用
PluginException把错误归到正确插件。 - 平台 API 弃用提示不要只消警告，要确认迁移路径。
- 动态卸载问题看
com.intellij.ide.plugins.DynamicPlugins日志分类。
Plugin Verifier¶
Plugin Verifier 检查插件二进制与目标 IDE 构建之间的兼容性。Gradle 2.x 可用任务：
./gradlew verifyPlugin
./gradlew runPluginVerifier
发布到 Marketplace 的插件也会由平台侧运行兼容性检查，但本地和 CI 仍应提前执行，避免发布后才发现缺类、方法签名变化或 API 状态问题。
API 状态检查¶
官方文档强调的 API 状态：
| 标记 | 含义 | 插件策略 |
|---|---|---|
@ApiStatus.Experimental |
不稳定，可能变化或移除 | 只在可接受升级成本时使用 |
@ApiStatus.Internal |
内部 API | 不应使用，查找替代 API |
@ApiStatus.ScheduledForRemoval |
计划移除 | 尽快迁移 |
@ApiStatus.Obsolete |
已有更好替代 | 新代码不要使用 |
@ApiStatus.NonExtendable |
不允许扩展或实现 | 不要继承/实现 |
@ApiStatus.OverrideOnly |
只能覆盖，不能直接调用 | 只在扩展实现中覆写 |
IDE 检查可以提前发现：
- 使用了不适用于最低支持 IDE 版本的 API。
plugin.xml使用了 deprecated、experimental、internal 的扩展点。- 扩展实现类中存在静态初始化。
- Listener 实现了不该实现的生命周期接口。
- Map key 可能泄漏 FileType/Language 或插件类加载器。
CI 推荐门禁¶
最小 CI 门禁：
./gradlew test
./gradlew buildPlugin
./gradlew verifyPlugin
更完整的发布前门禁：
- 运行单元/夹具测试。
- 对所有支持的 IDE 版本运行 Plugin Verifier。
- 构建并安装本地 ZIP。
- 验证动态安装、更新、卸载。
- 验证目标产品，而不只验证 IntelliJ IDEA。
- 检查 Marketplace 描述、图标、截图和变更说明。