VSCode 如何配置 ESLint 自动修复保存时生效设置

要在 VSCode 保存时自动修复 ESLint 错误，核心是在 settings.json 中显式配置 editor.codeActionsOnSave 并启用 source.fixAll.eslint，同时确保项目根目录有有效的 ESLint 配置文件且插件已正确加载。

先说结论：默认不会自动修复，必须手动写入配置项才能触发保存时的 fix 动作。

适合：JavaScript、TypeScript、Vue 等前端项目，且已安装 ESLint 依赖。
先准备：安装官方 ESLint 插件，确认项目根目录存在.eslintrc 或 eslint.config.js。
验收：保存文件后观察代码是否变动，并检查输出通道有无报错。

命令速用版

直接将以下配置写入工作区或用户级的 settings.json 文件中（VSCode 支持 JSONC 格式，可写注释）：

{
    "editor.codeActionsOnSave": {
        "source.fixAll.eslint": true
    },
    // "eslint.validate": ["javascript", "typescript", "vue"], // 新版插件已自动识别，此项可选
    "editor.formatOnSave": false
}

版本兼容与配置差异

ESLint 插件版本不同，配置行为有所差异，需注意以下区别：

v2.4.0 及以上：自动检测语言类型，eslint.validate 配置项已不再推荐，保留可能产生警告。
旧版本：必须手动配置 eslint.validate 指定语言，否则插件不工作。
建议：保持插件为最新，移除冗余配置项以减少冲突。

为什么会这样

VSCode 的 ESLint 插件默认只做高亮和提示，保存时不会主动修改代码。这是为了防止编辑器意外覆盖用户手动编写的格式。必须通过 editor.codeActionsOnSave 显式告诉编辑器，在保存动作发生时，调用 ESLint 的 source.fixAll 能力。如果只装了插件没配这个开关，即使规则标记为可修复，保存后也不会有任何变化。

分步处理

1. 确认插件与依赖

确保已安装由 Microsoft 发布的官方 ESLint 插件。在项目终端运行 npm install eslint `--save-dev`，确认 node_modules 中存在 eslint 可执行文件。如果项目用 pnpm 或 yarn，需确保插件能正确定位到本地依赖。

2. 检查配置文件

VSCode 插件依赖项目根目录下的配置文件启动。确认存在.eslintrc.js、.eslintrc.cjs 或 eslint.config.js。如果是 monorepo 结构，确保 VSCode 打开的是包含配置文件的子包目录，否则插件会报 No ESLint configuration found。

3. 写入设置

打开设置（Ctrl+,），搜索 settings.json。粘贴“命令速用版”中的配置。注意 editor.codeActionsOnSave 的值必须是对象，不能写成 true 或 false。若项目使用 Prettier，建议将 editor.formatOnSave 设为 false，避免格式化工具冲突。

4. 特殊语言支持

对于 Vue 文件，需安装 eslint-plugin-vue。对于 TypeScript，确保 parser 设置为@typescript-eslint/parser，且在 parserOptions 中指定 project 路径指向 tsconfig.json。

怎么验证是否生效

1. 状态栏图标

打开一个 JS 或 TS 文件，查看右下角状态栏是否有 ESLint 图标亮起。若显示 Disabled，说明文件未匹配配置或插件未加载。

2. 输出通道日志

按 Ctrl+Shift+P 打开命令面板，运行 ESLint: Show Output Channel。查看是否有 Using configuration from...字样。若出现 Failed to load config 或 Cannot find module，说明配置路径或依赖有问题。

3. 保存测试

故意写一段可修复的代码（如多余的分号或缺失的引号），按 Ctrl+S 保存。若代码自动修正且波浪线消失，说明配置生效。

常见坑

1. 配置作用域覆盖

项目根目录下的.vscode/settings.json 会覆盖用户全局设置。如果改了全局没生效，检查工作区设置是否禁用了相关选项。

2. Flat Config 版本

若使用 eslint.config.js 新格式，需确保 ESLint 版本在 v8.50+ 且插件版本较新，否则可能无法识别配置。

3. 规则不可修复

并非所有错误都能自动修复。只有规则元数据中标记为 fixable 的问题才会被处理，逻辑错误或变量命名问题通常不会自动修改。

4. 导入排序冲突

避免同时开启 source.organizeImports 和 ESLint 的 import/order 规则，两者可能打架导致保存后 import 块反复重排。

笙亿网络策划