WebStorm 保存格式化冲突与多次热更新问题排查笔记

场景：Vue 3 + TypeScript + Vite 项目，ESLint + Stylelint + Prettier 三件套，WebStorm 开发。

一、问题现象

1. WebStorm 保存 .vue / .ts 文件时，格式化不生效或「跳动」；
2. 一次保存触发热更新两次甚至更多；
3. 部分文件（含混合 type 导入的）保存后完全不格式化，或产出「缝合怪」格式（一行内既有 Prettier 风格又有 IDE 对齐空格）；
4. 文件内残留双空格、对象字面量列对齐等脏格式，手动保存也无法清除。

二、环境背景

组件	版本/状态
项目内 Prettier	老版本（锁定在 package.json）
全局 Prettier	最新版（排查中期临时引入绕坑）
ESLint	vue3-recommended + @typescript-eslint/recommended + simple-import-sort
eslint-config-prettier	已安装，但 extends 中被注释，从未生效
Stylelint	+ stylelint-config-prettier
WebStorm	Actions on Save 四条链全开

项目格式化体系是「Prettier 全责制」：ESLint/Stylelint 接了 *-config-prettier 关闭格式规则，所有格式职责都在 Prettier；而 Prettier 从未做过全仓格式化，一直处于「谁保存谁局部格式化」的松散状态——这类仓库里，格式问题会长期潜伏，直到某次语法升级或配置改动集中爆发。

三、根因（共四层，逐层剥开）

1. 老版本 Prettier 解析不了新语法

• import { type Ref } from 'vue'（inline type import，TS 4.5 语法，2021.11）→ Prettier ≥2.7 才支持；
• interface X extends Y['k']（TS 4.9 语法，2022.11）→ Prettier ≥2.8 才支持；
• 老版本直接抛 SyntaxError，格式化在解析阶段整体中止。CLI 下 .vue 文件走 vue 解析路径侥幸能过，.ts 必挂；WebStorm 集成的调用路径又与 CLI 不同，表现更混乱。

2. eslint-config-prettier 未启用，ESLint 与 Prettier 口径相反

.eslintrc.cjs 的 extends 里 'prettier'、'prettier/vue' 被注释，导致 plugin:vue/vue3-recommended 的全套模板格式规则生效：

• vue/max-attributes-per-line（每属性一行）←→ Prettier 按行宽合并属性；
• vue/singleline-html-element-content-newline（内容强制换行）←→ Prettier 无对应选项，必然合并；
• 两者每次保存朝相反方向修改，写盘两遍、热更新跳两次、永远振荡。

注意版本细节：eslint-config-prettier 7.x 中 Vue 规则在独立的 prettier/vue 入口（8.0 才合并进主入口），只启用 'prettier' 管不到模板规则。

3. WebStorm「执行重新设置代码格式操作时运行」拦截路径存在 bug

该路径对含混合 type 导入的文件会静默失败（无日志、无报错），并退回 IDE 自带 formatter 接手，产出「Prettier 风格开头 + IDE 列对齐收尾 + 行尾双空格」的缝合格式。同一文件用 CLI、stdin（--stdin-filepath）、API 三种方式直调最新版 prettier 均正常——问题仅在 reformat 拦截路径。

4. WebStorm Optimize imports 与 simple-import-sort 互搏

两者对命名导入符（尤其 type X 与 x 混排时）的排序位置意见不一致，每次保存互相重排。

四、排查方法（可复用的手段）

1. 规则生效验证：npx eslint --print-config <file> + 解析 JSON，确认最终合并后的规则状态；
2. 配置合法性：node -e "require('./.eslintrc.cjs')"、python3 -c "import json;json.load(open('.prettierrc'))"（本例中配置文件里一个非法键长期产生 Ignored unknown option 告警而无人察觉）；
3. Prettier 解析验证：--check / --debug-check 区分「格式差异（warn）」和「解析失败（error）」；用 stdin 方式 cat file | prettier --stdin-filepath <path> 精确复现 IDE 的调用方式；
4. API 层验证：prettier.format() 直调，排除 CLI 与 API 的行为差异；
5. IDE 侧取证：
   • ~/Library/Logs/JetBrains/WebStorm*/idea.log 查运行期报错；
   • Help → Diagnostic Tools → Debug Log Settings 添加 #com.intellij.prettierjs 开调试日志；
   • 注意：prettier 插件对成功调用不打日志，零日志不能证明零调用；
6. 写盘监视器（本次定案的关键手段）：20ms 轮询 + st_mtime_ns + 内容 sha1，记录每次真实写盘及内容是否变化——能区分「工具互搏改写」和「仅时间戳变化」。

五、实测数据（写盘监视器）

时间	内容哈希	含义
T0	be898f944b	基准（收敛状态）
T1	272e02aba0（+7 字节）	手工制造的格式问题落盘
T2	be898f944b（回到基准）	修复链执行，恢复规范状态

结论：

• 不编辑直接 Cmd+S：零写盘 → ESLint 与 Prettier 已不再互搏（收敛配置生效的铁证）；
• 编辑后保存：两次写盘 = 第一次写「原始编辑内容」（WebStorm 先保存后修复的固有流程）+ 第二次写「修复结果」。只要开着保存时自动修复，这就是固有成本，与配置无关。

六、最终方案

1. .eslintrc.cjs（格式判定权收敛到 Prettier）

extends: [
  'plugin:vue/vue3-recommended',
  'plugin:@typescript-eslint/recommended',
  // 关闭所有与 Prettier 冲突的格式规则（prettier/vue 负责模板格式规则）
  'prettier',
  'prettier/vue',
],
rules: {
  // 团队约定：多属性每属性一行；.prettierrc 的 singleAttributePerLine 与之对齐
  'vue/max-attributes-per-line': ['warn', { singleline: { max: 1 }, multiline: { max: 1 } }],
  // ...
}

原则：Prettier 能模仿的规则 → 配置对齐；Prettier 无法模仿的规则（如内容换行类）→ 由 prettier/vue 直接关闭；代码质量规则（如 vue/attributes-order）→ 保留（Prettier 不重排属性语义，无冲突）。

2. .prettierrc

{
  "singleQuote": true,
  "trailingComma": "all",
  "printWidth": 120,
  "proseWrap": "never",
  "arrowParens": "avoid",
  "singleAttributePerLine": true
}

（若配置文件里存在 Prettier 不认识的键会持续产生告警，应清理；.prettierignore 文件本身仍然生效）

3. WebStorm 配置

• Languages & Frameworks → JavaScript → Prettier：
  • 「执行’重新设置代码格式’操作时运行」取消（该拦截路径有 bug）；
  • 「保存时运行」勾选（直连通道，且排在 ESLint/Stylelint 之后）；
  • 「首选 Prettier 配置而不是 IDE 代码样式」保持勾选（防止 IDE 原生格式化产出 Prettier 不认可的文本）；
• Tools → Actions on Save：「重新设置代码格式」❌、「优化 import」❌、「运行 eslint –fix」✅、「运行 stylelint –fix」✅、「运行 Prettier」✅。

4. 代码规范补充

模板中的多语句内联 handler（@click="{ a(); b(); }"）会触发 WebStorm Vue 表达式解析器误报，进而打断格式化链路。应提取为方法：

// 模板：@click="handleSearch"
const handleSearch = () => {
  pagination.current = 1;
  getApplyBuyOutList();
};

注意 defineComponent 风格的文件，新方法必须加进 setup 的 return。

七、遗留事项

1. 项目内 Prettier 升级到最新稳定版（保证 CLI、IDE、CI 全员同版本）：完成后 WebStorm 改回「自动 Prettier 配置」，全局安装退役；
2. 全仓一次性 prettier --write（纯格式 diff，数量可能很大），须单独提交、不混业务；
3. .eslintrc.cjs + .prettierrc 的收敛配置应开独立 chore(eslint) 分支固化，不混业务 MR。

八、经验总结

1. 「保存跳动 N 次」的本质：每次写盘都会触发 Vite 热更新，写盘次数 = 工具链中有实际内容变更的次数。收敛工具口径后，修复链只剩「原始内容 + 修复结果」两次固有写盘；
2. 格式化只能有一个裁判。多个工具都持有格式话语权时，必然振荡；调和方式只有两种——能对齐的用配置对齐，不能对齐的关掉；
3. IDE 集成 ≠ CLI。同一工具，CLI、stdin、API、IDE 拦截四种路径行为可能不同，排查时要逐一复现；
4. 日志为零 ≠ 没执行。prettier 插件成功调用不打日志，需要用文件写入监视器这类外部观测手段拿证据；
5. 升级解析类工具前，先摸清仓库里超出其语法能力的存量（TS 4.5 inline type import、TS 4.9 satisfies 分别对应 Prettier ≥2.7 / ≥2.8）；
6. 依赖「装了但没启用」的防护配置（如被注释的 extends 项）是隐性炸弹，接手项目时值得先跑一遍 --print-config 确认真实生效的规则集。

附：关键命令速查

# 查看 ESLint 最终生效的规则
npx eslint --print-config <file> | python3 -m json.tool

# 验证 Prettier 解析（区分格式差异与语法错误）
prettier --check <file>        # warn=格式差异, error=解析失败
prettier --debug-check <file>

# 模拟 WebStorm 的 stdin 调用方式
cat file | prettier --stdin-filepath <path>

# eslint-config-prettier 冲突自检
npx eslint-config-prettier <file>

# WebStorm 日志
~/Library/Logs/JetBrains/WebStorm*/idea.log