许多开发者在使用 VSCode 安装 ESLint 插件后，发现代码检查并未如预期自动生效——这其实是一个普遍存在的误区。插件本身只充当“调度器”，负责调用项目中的 ESLint 可执行文件。要让整个流程正常运转，必须同时满足三个条件：本地已安装 ESLint、配置文件能被正确加载、语言模式需匹配。任何一个环节出现问题，都会导致“无波浪线”、“保存不修复”甚至 TypeScript 文件完全不检查的静默失效现象。
首先确认本地 ESLint 是否可用。插件默认仅在项目目录下的 node_modules/.bin 中查找 eslint 可执行文件——若找不到则直接不工作，且不给出任何提示。在项目根目录的终端中执行 npx eslint --version：有输出说明已安装；若报错，则需补充安装：npm install eslint --save-dev。如果使用 pnpm 或 yarn@3+，请检查 node_modules/.bin/eslint 文件是否存在——若不存在，则需在 VSCode 设置中显式指定包管理器，例如 "eslint.packageManager": "pnpm"，该值必须与实际使用的包管理器一致。此外，不建议依赖全局安装的 ESLint：VSCode 插件默认忽略全局安装，即使终端中 eslint --version 可运行，项目内也可能静默失效。
配置文件是否被正确识别
VSCode 插件对配置文件的格式较为敏感，且不会向上递归查找——仅识别工作区根目录下的合法配置文件。需要注意的是，截至 2026 年中，当前版本的 ESLint 对 eslint.config.js 的支持仍不够稳定。
优先推荐使用 .eslintrc.cjs（CommonJS 格式），导出时使用 module.exports = { ... }，避免使用 export default 或 ESM 语法。同时，确保配置中包含 root: true，否则可能误读父目录中的配置，导致规则冲突，产生一些难以预料的检查结果。若仍不确定配置是否被加载，可打开命令面板（Ctrl+Shift+P），执行 ESLint: Show Output Channel，查看日志中是否有 Using configuration from /path/to/.eslintrc.cjs 这样的信息——若无，则说明配置文件未被识别。
为什么 TS/JSX/Vue 文件不校验
ESLint 默认仅解析纯 JavaScript。若遇到 .ts、.tsx、.vue 等文件不检查的问题，通常是因为未配置对应的解析器。ESLint 会直接跳过整个文件，连语法错误也不报。
对于 TypeScript 项目，必须同时满足三个条件：parser: "@typescript-eslint/parser"、安装 @typescript-eslint/parser 和 @typescript-eslint/eslint-plugin，并且 parserOptions.project 需指向一个有效的 tsconfig.json 路径，例如 "./tsconfig.json"。如果是 React JSX 文件，需要启用 ecmaFeatures.jsx: true，并确保 VSCode 的 eslint.validate 设置中包含 "javascriptreact" 或 "typescriptreact"。Vue 单文件组件则更复杂，需额外设置 parserOptions.parser 子项，例如：{"parser": "vue-eslint-parser", "parserOptions": {"parser": "@typescript-eslint/parser"}}。
保存时自动修复为什么没反应
许多开发者希望保存时自动修复代码，却发现无反应。这里有一个关键点：eslint.autoFixOnSave 配置早在几年前已被废弃。现在必须使用 VSCode 的统一 Code Action 机制，且该机制仅对标记为 fixable 的规则生效，例如 semi、quotes 等规则可自动修复，但像 no-console 这类规则永远无法自动删除 console.log。
正确的配置方式是在项目根目录的 .vscode/settings.json 中写入："editor.codeActionsOnSave": {"source.fixAll.eslint": true}。同时，必须配合 "editor.defaultFormatter": "dbaeumer.vscode-eslint"，并针对 [javascript]、[typescript] 等语言标识分别设置，否则 VSCode 可能会调用 Prettier 或内置格式化器，覆盖 ESLint 的修复结果。若同时开启了 "editor.formatOnSave": true，务必将其关闭，或确保 Prettier 不接管 JS/TS 文件，否则两次格式化会相互冲突，导致修复无效。
最后，最容易忽略的其实是语言模式和 parserOptions.project。可以查看右下角状态栏，若显示为“Plain Text”或“JavaScript React”却没有安装 eslint-plugin-react，或者 TypeScript 规则不触发却忘了填写 parserOptions.project——这两处一旦出错，整个文件就等于根本没有进入 ESLint 的检查流水线。
