版本迁移、破坏性变更与内部 API¶

IntelliJ Platform 每年多个版本持续演进，插件维护必须把“升级目标平台”当成常规工程流程，而不是发布前临时修一轮编译错误。官方维护了 Incompatible Changes 页面，列出已知破坏性变更和迁移建议。

基本策略¶

每次升级目标 IDE 版本时：

阅读对应年份的 Incompatible Changes。
升级 IntelliJ Platform Gradle Plugin。
调整 Java/Kotlin 目标版本。
运行 IDE inspections。
运行测试。
运行 Plugin Verifier。
在目标产品中安装本地 ZIP。
检查动态卸载和 Remote Development 影响。

不要只看编译是否通过。很多问题是二进制兼容、运行时扩展点变化、API 状态或产品模块拆分。

Java 与 Gradle Plugin 版本¶

官方 2025/2026 破坏性变更页都强调：

目标平台	Java
2024.2+	Java 21
2022.3+	Java 17

Gradle 插件选择：

目标平台	建议
2024.2+	需要 IntelliJ Platform Gradle Plugin 2.x
2022.3+	推荐 2.x；旧 1.x 已 obsolete

实际项目还要看 tools-intellij-platform-gradle-plugin.html 的最新最低要求。当前官方 Gradle Plugin 2.x 页面要求 Gradle 9.0.0、Java Runtime 17、IntelliJ Platform 2023.3+。

API 状态¶

不要使用这些 API，或至少把风险显式记录：

标记	迁移策略
`@ApiStatus.Internal` / `@IntellijInternalApi`	查 Internal API Migration，寻找公开替代
`@ApiStatus.Experimental`	不稳定，升级可能破坏
`@ApiStatus.ScheduledForRemoval`	尽快迁移
`@Deprecated(forRemoval=true)`	不要等待移除后再处理
`@ApiStatus.Obsolete`	新代码不要使用
`@ApiStatus.NonExtendable`	不要继承或实现
`@ApiStatus.OverrideOnly`	只能覆写，不要直接调用

IDE inspections 和 Plugin DevKit 检查能提前发现很多问题。

2026.1 重点变更¶

截至 2026-06-18 官方页面列出的重点包括：

AWT input event handlers 不再在 write-intent lock 下运行。需要访问 PSI 或其他受保护数据时，显式使用 ReadAction.nonBlocking().submit() 或 coroutine readAction {}。
PolySymbols 中部分 API 调整，例如 PolySymbol.getOrigin() 移除，PolySymbolQualifiedKind 重命名为 PolySymbolKind。
Java plugin 拆分为多个 classloader 下的模块。标准 <depends>com.intellij.java</depends> 通常不受影响；直接依赖 Java plugin 内部模块的插件需要更新依赖。

2025 重点变更模式¶

2025 年变更反复出现几类模式：

核心模块拆分，需要在 Gradle 中显式 bundledModule(<moduleName>)。
Write Action / Read Action / Write Intent API 清理。
SwingUtilities.invokeLater、Dispatchers.Main 不再隐式持有 write-intent lock。
Kotlin UI DSL Version 1 在 2025.1 后不可用，应迁移到 UI DSL v2。
WebSymbols 改名为 PolySymbols。
JavaScript/TypeScript、Database、External System 等产品插件 API 变动。

这说明升级风险往往来自“隐式行为不再隐式”和“模块拆分后依赖需要显式化”。

迁移工作流¶

推荐分支流程：

upgrade/idea-2026.1
  1. bump platform version
  2. bump Gradle plugin / JDK / Kotlin if needed
  3. fix compilation
  4. fix inspections
  5. run tests
  6. run verifier matrix
  7. manual smoke test
  8. release beta/eap

每个迁移 PR 应记录：

目标平台版本。
最低支持版本是否变化。
受影响 API。
是否新增 bundledPlugin() / bundledModule()。
是否影响 Remote Development。
Plugin Verifier 覆盖范围。

验证矩阵¶

至少覆盖：

最低支持版本。
最新稳定版本。
即将发布的 EAP。
每个目标产品。
可选依赖存在/不存在两种状态。

发布前命令：

./gradlew test
./gradlew buildPlugin
./gradlew verifyPlugin
./gradlew runPluginVerifier

如果插件使用产品专属 API，比如 JavaScript、Database、Python、Kotlin，应针对这些插件版本单独看 Incompatible Changes 中对应小节。

迁移检查清单¶

没有新增 internal / impl API 使用。
所有 @ScheduledForRemoval 都有处理计划。
Java/Kotlin target 与目标平台一致。
Gradle plugin 版本符合官方要求。
模块拆分后 Gradle 依赖显式声明。
plugin.xml 与 Gradle 依赖一致。
UI DSL 已迁移到当前版本。
Threading 代码不依赖隐式 write-intent lock。
Beta/EAP 渠道先验证，再发默认渠道。