WebStorm EAP 插件不兼容时，手动放开 until-build

WebStorm 升级 EAP 版本时，经常会遇到一个有点尴尬的提示：某个插件不兼容，要求 IDE 内部版本必须是某个 build 或者更低。

这类提示不一定说明插件真的跑不了。

JetBrains 插件包里通常有一个 META-INF/plugin.xml，里面用 <idea-version> 声明兼容范围。比如：

<idea-version since-build="253" until-build="261.*"/>

since-build 是最低可用 build，until-build 是最高可用 build。如果插件作者还没来得及更新这个上限，EAP 一升级，IDE 就会把它拦下来。

卡点在于：这个上限只是插件声明，不是运行时证明。插件可能真的用了不兼容 API，也可能只是 until-build 没跟上。

于是写了两个小脚本，用来批量处理已安装插件 jar 里的这个声明。

脚本放在哪里

这两个脚本会跟博客一起作为静态文件发布：

https://shengsheng.fun/files/webstorm-eap-plugin-compat/force-webstorm-plugin-compat.sh
https://shengsheng.fun/files/webstorm-eap-plugin-compat/force-webstorm-plugin-compat.ps1

如果你平时访问的是带 www 的域名，也可以把前面的域名换成：

https://www.shengsheng.fun

源码里对应放在 source/files/webstorm-eap-plugin-compat/。文章文件仍然是 source/_posts/webstorm-eap-plugin-compat.md，两边使用同一个 slug，方便以后靠文件名关联。

它们做的事情一样：自动找 WebStorm 的用户插件目录，扫描所有包含 META-INF/plugin.xml 的 jar，把 <idea-version> 上的 until-build 和 strict-until-build 去掉。

脚本不会去改 WebStorm 应用包里的 bundled 插件，只处理用户插件目录。

macOS / Linux / Git Bash

更建议先下载，看一眼，再执行。

curl -fsSLO https://shengsheng.fun/files/webstorm-eap-plugin-compat/force-webstorm-plugin-compat.sh
sh force-webstorm-plugin-compat.sh --dry-run
sh force-webstorm-plugin-compat.sh

如果只是想直接跑，也可以这样：

curl -fsSL https://shengsheng.fun/files/webstorm-eap-plugin-compat/force-webstorm-plugin-compat.sh | sh -s -- --dry-run
curl -fsSL https://shengsheng.fun/files/webstorm-eap-plugin-compat/force-webstorm-plugin-compat.sh | sh

这里特意写成 sh。脚本外层已经按 POSIX shell 处理，所以不依赖 Bash；真正改 jar 的逻辑放在内嵌 Python 里。macOS / Linux / Git Bash 环境里只要有 python3 或 python 就能跑。

如果 WebStorm 插件目录比较特殊，可以手动指定：

sh force-webstorm-plugin-compat.sh --plugins-dir "$HOME/Library/Application Support/JetBrains/WebStorm2026.2/plugins"

也可以只列出脚本识别到的目录：

sh force-webstorm-plugin-compat.sh --list-dirs

Windows PowerShell

Windows 上更建议用 .ps1。它用 .NET 的 Zip API 改 jar，不依赖 Python。

先下载到临时目录再 dry-run：

$url = 'https://shengsheng.fun/files/webstorm-eap-plugin-compat/force-webstorm-plugin-compat.ps1'
$file = Join-Path $env:TEMP 'force-webstorm-plugin-compat.ps1'

Invoke-WebRequest $url -OutFile $file -UseBasicParsing
powershell -ExecutionPolicy Bypass -File $file -DryRun
powershell -ExecutionPolicy Bypass -File $file

如果你明确知道自己要直接执行，也可以用一行：

(Invoke-WebRequest 'https://shengsheng.fun/files/webstorm-eap-plugin-compat/force-webstorm-plugin-compat.ps1' -UseBasicParsing).Content | Invoke-Expression

这条命令不能方便地传 -DryRun，所以还是更推荐先下载再执行。

回滚怎么做

脚本每次真正修改前都会备份原 jar，并生成一个 manifest.tsv。

macOS / Linux 默认备份到：

~/.webstorm-plugin-compat-backups/<timestamp>

Windows 默认备份到：

%LOCALAPPDATA%\JetBrains\webstorm-plugin-compat-backups\<timestamp>

执行完成后，脚本会打印类似这样的路径：

备份目录：/Users/me/.webstorm-plugin-compat-backups/20260529-103523

要恢复，用这条：

sh force-webstorm-plugin-compat.sh --restore "/Users/me/.webstorm-plugin-compat-backups/20260529-103523"

PowerShell 对应是：

powershell -ExecutionPolicy Bypass -File .\force-webstorm-plugin-compat.ps1 -Restore "C:\Users\me\AppData\Local\JetBrains\webstorm-plugin-compat-backups\20260529-103523"

备份里会记录原 jar 路径、备份 jar 路径、原文件 sha256、插件 id、插件名、插件版本，以及修改前后的 <idea-version> 标签。

脚本具体改了什么

脚本只处理 META-INF/plugin.xml 里的 <idea-version> 标签。

比如原来是：

<idea-version since-build="253" until-build="261.*" strict-until-build="261.9999"/>

处理后会变成：

<idea-version since-build="253"/>

它不会改 since-build。

原因很简单：最低版本限制通常是插件真实依赖的 API 起点，随便往低改意义不大。EAP 升级时最常见的卡点，是插件作者还没把最高版本范围放开。

JetBrains 官方文档里也能看到这个模型：插件通过 since-build、until-build、strict-until-build 描述兼容区间。如果省略 until-build，含义就是从 since-build 开始兼容未来 IDE build。

参考：Plugin Configuration File 和 Build Number Ranges。

有哪些风险

这个脚本只能绕过声明检查，不能保证插件真的兼容。

如果插件内部调用了新版 WebStorm 已经删除或改签名的 API，IDE 启动后还是可能报错，比如：

NoSuchMethodError
ClassNotFoundException
PluginException

这时就不要硬扛，直接用备份恢复，或者删除对应插件目录。

使用原则是：

先关掉 WebStorm。
先跑 --dry-run。
只在 EAP 阻塞日常工作时使用。
改完启动 IDE，确认插件功能真的正常。
插件正式更新后，优先回到官方版本。

这件事适合当临时补丁，不适合当长期方案。

为什么不直接手改

当然可以手改。

大概流程是找到插件目录，进 jar，解出 META-INF/plugin.xml，删掉 until-build，再写回 jar。

问题是插件一多就麻烦。WebStorm EAP 一次升级后，可能不是一个插件被拦，而是一批插件都被上限卡住。手动改每个 jar 不难，但很烦，也容易忘记自己改过什么。

脚本做了几件机械活：

自动找常见 WebStorm 插件目录
扫描 jar 里的 META-INF/plugin.xml
只改带 until-build / strict-until-build 的插件
修改前备份原 jar
生成 manifest.tsv 方便恢复
提供 --dry-run 看改动范围

它解决的不是「插件兼容性」这个复杂问题，而是把「确认只是声明上限落后」之后的重复操作自动化。

使用边界

如果用的是稳定版 WebStorm，不建议没事跑这个。

它更适合 EAP 用户：IDE 升级得很快，插件作者还没发布新包，但你判断这个插件大概率只是声明范围没更新。

这时候，用它先把路临时打通；等插件正式更新，再回到正常升级路径。