WebStorm 主题插件被升级覆盖后，自己打一个固定版

WebStorm 升级以后，每天盯着看的颜色突然不对了，比少一个功能按钮还烦。

我之前一直用一套 One Dark 风格的主题。升级 WebStorm 后，它像是被系统顺手带走了：插件市场里搜 one dark theme，能搜到几个名字很像的，但装完以后按钮、编辑器、选中态、弹窗颜色都不是原来的感觉。

后来翻了一圈本地配置，又逐项对比旧版和新版颜色表，才发现问题不只是名字变了。新版还换掉了旧版的 UI 色表，旧的灰蓝背景、硬朗按钮和输入框颜色没有作为一个可选主题保留下来。对我这种已经适应旧色的人来说，升级后的几个 One Dark 主题都不对味，只能把旧主题固定下来继续用。

这次整理出的固定版插件可以直接下载。

安装方式：

Settings | Plugins | 齿轮菜单 | Install Plugin from Disk...

选中这个 JAR，重启 WebStorm，然后在 Settings | Appearance & Behavior | Appearance 里选择 Sheng Atom OneDark Theme。

这个包是从旧主题插件整理出来的本地固定版，核心改动是换成私有插件 ID，避免以后再被 Marketplace 上同一条插件线的新版覆盖。

先从本地找旧插件

WebStorm 升级时不会只留下当前界面。用户插件、主题选择、编辑器配色、启动日志、Toolbox 备份，都会留下线索。

macOS 上可以先看这些目录：

~/Library/Application Support/JetBrains/WebStorm2026.1/plugins
~/Library/Application Support/JetBrains/WebStorm2026.1/options
~/Library/Caches/JetBrains/WebStorm2026.1/plugins
~/Library/Logs/JetBrains/WebStorm2026.1/idea.log

如果 WebStorm 是通过 JetBrains Toolbox 升级的，旧版本配置还可能在备份目录里：

~/Library/Application Support/JetBrains/WebStorm2026.1-backup/<timestamp>/plugins

找到可疑 JAR 后，不用急着安装，先拆开看 plugin.xml：

unzip -p atom-onedark-theme.jar META-INF/plugin.xml | sed -n '1,120p'

主题 JSON 也可以直接读：

unzip -p atom-onedark-theme.jar atom_onedark.theme.json \
  | python3 -m json.tool \
  | sed -n '1,80p'

这次在 Toolbox 备份里找到的旧插件，META-INF/plugin.xml 里是这样的：

<id>github.cweijan.test-theme</id>
<name>Atom OneDark Theme</name>
<version>1.6</version>

这三个字段基本就把旧身份钉住了：它叫 Atom OneDark Theme，插件 ID 是 github.cweijan.test-theme，版本是 1.6。

名字为什么对不上

JetBrains 插件市场里的展示名可以改，插件 ID 才是更稳定的身份。

旧插件的 xmlId 是 github.cweijan.test-theme。2026-06-26 查 JetBrains Marketplace 时，同一个 xmlId 对应的是 One Dark Modern Theme，Marketplace 插件 ID 是 12178，版本线已经到了 2.x。

另一个常见搜索结果 One Dark Theme 是 Mark Skelton 维护的另一套主题，xmlId 是：

com.markskelton.one-dark-theme

它名字很像，但和 github.cweijan.test-theme 不是同一条插件线。所以「装了一个 One Dark 还是不像以前」很正常：搜索命中了同类主题，不一定命中原来那一个。

WebStorm 当前选择了哪个主题，可以看：

~/Library/Application Support/JetBrains/WebStorm2026.1/options/laf.xml

当前编辑器配色可以看：

~/Library/Application Support/JetBrains/WebStorm2026.1/options/colors.scheme.xml

有时候 UI 主题已经变成新的，编辑器配色还挂着旧 scheme 名；也有时候 laf.xml 里记录的主题 ID 对应插件已经不在了。界面看起来「半旧半新」，往往就是这些配置没对齐。

新版丢掉了旧 UI 色表

一开始我也怀疑过：新版插件可能还带着旧颜色，只是我没有选对主题。检查当前 Marketplace 上的 One Dark Modern Theme 2.0.5 后，能看到它只有一个主题入口：

<themeProvider id="one-dark-modern-theme" path="/theme/one_dark_modern.theme.json" />

包里对应的主题文件也只有：

theme/one_dark_modern.theme.json
theme/one_dark_modern.xml

旧版 Atom OneDark Theme 1.6 的 atom_onedark.theme.json 和 atom_onedark.xml 没有作为另一个可选主题保留下来。

更关键的是颜色本身也对不上。旧版最明显的 UI 色是这一组：

主背景                  #343C4A
按钮背景                #424954
输入框背景              #454C5C
Search Everywhere 背景  #474C59
Tab 选中背景            #3B4252
Tab 下划线              #848AA1
按钮圆角                0

新版 One Dark Modern 已经换成了另一组：

主背景                  #21252b
按钮背景                #2c313c
输入框背景              #252931
Search Everywhere 背景  #252931
Tab 选中背景            #21252b
Tab 下划线              #528bff
按钮圆角                8

另一个插件 One Dark Theme 里的 One Dark / Islands / Vivid 也更接近 #21252b 和 #282c34 这组深底色。它们和旧版的灰蓝 UI 不是同一个方向。

编辑器配色里确实还能看到一些 One Dark 系的相似颜色，比如 selection 和行号颜色有继承关系；但 WebStorm 外壳、按钮、弹窗、侧栏、输入框、Tab 这些每天扫来扫去的 UI 颜色已经换了。新版只保留了 One Dark Modern 这条主题路线，没有继续打包旧的 UI 色表。

这就是这个固定版主题的由来：新版继续往 One Dark Modern 走，旧版用户如果想保留 Atom OneDark Theme 1.6 的视觉，只能把旧颜色整理成一个独立主题。

同名主题不保证色表相同，逐项对照真实值

JetBrains 插件其实是什么

JetBrains IDE 插件最外层通常是一个 ZIP 或 JAR，里面至少会有：

META-INF/plugin.xml

IDE 启动或刷新插件时，会读取这个文件里的插件 ID、名字、版本、兼容范围、依赖和扩展点。

一个很小的插件也可能只有这些东西：

META-INF/plugin.xml
atom_onedark.theme.json
atom_onedark.xml

plugin.xml 负责告诉 IDE：「我提供了一个主题」。真正的颜色规则放在 theme JSON 里，编辑器里的代码高亮、光标行、diff、selection 等配色，通常放在 editor scheme XML 里。

JetBrains 的 Theme Structure 文档里也把主题插件拆成这几部分：

必需的 theme JSON；
plugin.xml 里的 themeProvider 声明；
可选的 editor scheme XML；
可选的背景图和图标资源。

主题插件最好保持单一职责。一个主题插件就只管主题，不要顺手塞别的动作、设置页或语言功能。这样升级 IDE 时风险小，自己维护起来也清楚。

插件身份、UI 主题和编辑器配色各自负责什么

主题是怎么被 IDE 加载的

主题入口在 plugin.xml 里：

<extensions defaultExtensionNs="com.intellij">
  <themeProvider
    id="fun.shengsheng.jetbrains.sheng-atom-onedark-theme.theme"
    path="atom_onedark.theme.json"/>
</extensions>

IDE 通过这两个字段识别主题并找到资源：

id 是这个主题 provider 的唯一 ID。不要复用别人插件里的 ID，也不要多个主题共用一个 ID。JetBrains 文档里也提醒过，themeProvider 的 ID 要保持唯一。
path 指向 theme JSON，IDE 通过它找到主题描述文件。

theme JSON 里最常见的是这些字段：

{
  "name": "Sheng Atom OneDark Theme",
  "dark": true,
  "author": "Local",
  "editorScheme": "/atom_onedark.xml",
  "ui": {
    "Panel.background": "#343C4A",
    "Button.startBackground": "#424954",
    "Button.endBackground": "#424954"
  }
}

name 是在 WebStorm 设置里看到的主题名。
dark 决定它基于浅色主题还是 Darcula 这类暗色基底。
editorScheme 指向编辑器配色 XML。没有它也能做 UI 主题，但编辑器高亮就会跟着用户当前 scheme 走。
ui 用于覆盖 UI 控件颜色，按钮、面板、弹窗、标签页、搜索框和工具窗口的颜色大多从这里改。

还有一个很实用的写法是先定义命名颜色，再在 ui 里引用：

{
  "colors": {
    "surface": "#343C4A",
    "surfaceHover": "#485569",
    "text": "#D0D0D9"
  },
  "ui": {
    "Panel.background": "surface",
    "Button.startBackground": "surfaceHover",
    "Button.endBackground": "surfaceHover",
    "Button.foreground": "text"
  }
}

命名颜色由具体控件引用，调色时只需修改对应的颜色定义，不用在几十个地方反复改同一个十六进制值。

主题 JSON 负责 UI 配色，editorScheme 指向的 XML 负责编辑器颜色。重新分发前仍要核对原主题许可，修改插件 ID 不会免除许可义务。完整内容见主题规则的调整示例弹窗。

这次固定版改了什么

我没有改旧主题的颜色，只改了插件身份和展示名。

旧插件：

<id>github.cweijan.test-theme</id>
<name>Atom OneDark Theme</name>
<version>1.6</version>

固定版：

<id>fun.shengsheng.jetbrains.sheng-atom-onedark-theme</id>
<name>Sheng Atom OneDark Theme</name>
<version>1.6.0-sheng.1</version>

<extensions defaultExtensionNs="com.intellij">
  <themeProvider
    id="fun.shengsheng.jetbrains.sheng-atom-onedark-theme.theme"
    path="atom_onedark.theme.json"/>
</extensions>

theme JSON 里的名字也改成了：

{
  "name": "Sheng Atom OneDark Theme",
  "dark": true,
  "author": "Local",
  "editorScheme": "/atom_onedark.xml"
}

这么改的目的很直接：让 WebStorm 把它当成独立的 Sheng 主题插件，而不是 Marketplace 上的 github.cweijan.test-theme。以后官方插件继续升级、改名、换配色，也不会影响这个固定版。

长期维护主题时，标准 Gradle 工程可以统一处理插件声明、资源和分发产物；只改一个自用固定版时仍可直接重打包。完整内容见最小主题插件模板弹窗。

怎么判断改得对不对

主题插件最容易出错的地方有几个：

plugin.xml 里的插件 ID 和 themeProvider id 跟别人冲突；
theme JSON 的 name 没改，导致设置里看不出来装的是哪一版；
editorScheme 路径写错，UI 主题生效了，编辑器配色没生效；
JAR 里文件路径多套了一层目录，比如 my-theme/META-INF/plugin.xml，IDE 找不到；
只改了 UI 颜色，没有改 editor scheme，于是代码区还是另一套颜色；
旧插件声明的 since-build / until-build 卡住了新 IDE。

检查 JAR 结构可以用：

jar tf sheng-atom-onedark-theme.jar | sed -n '1,80p'

META-INF/plugin.xml 必须在根路径下能看到。

检查 JSON：

unzip -p sheng-atom-onedark-theme.jar atom_onedark.theme.json \
  | python3 -m json.tool >/dev/null

检查 XML：

unzip -p sheng-atom-onedark-theme.jar META-INF/plugin.xml \
  | xmllint --noout -

装完以后，看三个地方：

Settings | Plugins
Settings | Appearance & Behavior | Appearance
Settings | Editor | Color Scheme

如果插件列表能看到，Appearance 里能选到主题，Editor Color Scheme 里也能看到对应 scheme，基本就跑通了。

显示名可能变化，查找插件时应按插件 ID 和实际文件位置区分旧版、新版与固定版。完整内容见插件身份与文件位置速查弹窗。

总结

升级后找不回熟悉的 One Dark，既有显示名与插件身份的差别，也有新版实际替换 UI 色表的变化。这次从本地旧 JAR 找回配色，保留旧颜色，改用独立插件 ID 和 themeProvider ID 打成固定版。主题加载仍依赖 plugin.xml、theme JSON 与 editor scheme XML 的正确引用，UI 外壳和编辑器配色需要分别核对。

只想保留一套旧配色时，直接重打 JAR 就能满足自用需要；需要长期维护、适配 IDE 版本或准备上传 Marketplace 时，建议用 Gradle 工程管理。独立 ID 解决的是后续被同一插件线覆盖的问题，不改变原资源的许可，公开分发仍需核对许可并保留要求的声明。

主题规则的调整示例

怎么自己调整主题规则

如果只是改一套已有主题，最快的办法是拆旧包。

先解压：

mkdir -p /tmp/atom-onedark-theme
cd /tmp/atom-onedark-theme
jar xf /path/to/atom-onedark-theme.jar

通常先看这几个文件：

META-INF/plugin.xml
*.theme.json
*.xml

改 UI 控件颜色，从 theme JSON 的 ui 下手。比如想改主面板、按钮、选中态：

{
  "ui": {
    "Panel.background": "#343C4A",
    "Button.startBackground": "#424954",
    "Button.endBackground": "#424954",
    "List.selectionBackground": "#4C5870"
  }
}

改编辑器里的颜色，要看 editorScheme 指向的 XML。比如光标行、选区、缩进线、diff 背景，很多都在这个文件里：

<scheme name="Sheng Atom OneDark Theme" version="142" parent_scheme="Darcula">
  <colors>
    <option name="CARET_ROW_COLOR" value="3a414f" />
    <option name="SELECTION_BACKGROUND_COLOR" value="4c5870" />
  </colors>
</scheme>

更稳的调法是先在 WebStorm 里打开：

Settings | Editor | Color Scheme

复制一份当前 scheme，手动调到差不多，再导出 XML。导出来的 XML 可以作为插件里的 editorScheme，比硬猜每个 option 名要省心。

改完以后重新打包：

cd /tmp/atom-onedark-theme
jar --create --file ../sheng-atom-onedark-theme.jar -C . .

然后从磁盘安装这个 JAR。

最小主题插件模板

从零做一个主题插件

如果想做一套真正属于自己的主题，建议走标准 Gradle 项目，而不是一直手改 JAR。

一个最小主题项目可以长这样：

my-webstorm-theme/
  settings.gradle.kts
  build.gradle.kts
  src/main/resources/META-INF/plugin.xml
  src/main/resources/my_theme.theme.json
  src/main/resources/my_theme.xml

完整工程放在下方源码区，包含 Gradle 配置、插件声明、主题 JSON 和编辑器配色 XML。插件和 themeProvider 的 ID 要分别唯一；editorScheme 路径要能找到包内 XML。只提供主题时，不需要 JavaScript / TypeScript 的语言 API 依赖。

这个示例把依赖仓库放在 build.gradle.kts，不在 settings 里同时启用 FAIL_ON_PROJECT_REPOS；否则项目声明仓库时会直接失败。需要集中到 settings 时，再按 Gradle 仓库模式和 IntelliJ Platform 配置一起迁移。

请接入 JetBrains 主题工程。
源码包根路径：https://shengsheng.fun/files/webstorm-onedark-classic-local-plugin/kits/jetbrains-theme-starter/
先读 README.md、MANIFEST.json、FILES.json 和 CHANGELOG.md，再按 FILES.json 获取源码。
迁移 copy/，调整目标 IDE、插件 ID、themeProvider ID 和主题名，检查两份配色资源的引用。

主题插件工程与配色文件正在加载代码工作区...

本机先准备 Gradle 9.0+ 和 JDK 17+，用 gradle wrapper --gradle-version 9.0.0 生成 wrapper；Windows 执行后续命令时使用 gradlew.bat。安装前还要检查生成包的资源路径，并在目标 IDE 验证外观。

然后打包：

./gradlew buildPlugin

JetBrains 的 Gradle 插件会生成用于测试和分发的 ZIP，默认在 build/distributions/ 下。这个 ZIP 可以直接通过 Install Plugin from Disk... 安装。

如果只是从旧主题 JAR 改一个自用固定版，前面那种 jar --create 就够了；如果打算长期维护、做版本号、换 IDE 版本、以后可能上传 Marketplace，就用 Gradle 项目。

插件身份与文件位置速查

插件身份速查

旧插件、新版和固定版的显示名并不相同，查找时按插件 ID 区分：

旧显示名：Atom OneDark Theme
旧 xmlId：github.cweijan.test-theme
旧版本：1.6

Marketplace 现名：One Dark Modern Theme
Marketplace 插件 ID：12178
2026-06-26 查到的当前版本线：2.x

容易混淆的另一个插件：One Dark Theme
另一个插件的 xmlId：com.markskelton.one-dark-theme
另一个插件的 Marketplace ID：11938

固定版显示名：Sheng Atom OneDark Theme
固定版插件 ID：fun.shengsheng.jetbrains.sheng-atom-onedark-theme
固定版版本：1.6.0-sheng.1