必须本地安装eslint并统一配置：npm install eslint --save-dev，配置文件置于项目根目录且非空，vscode需打开根目录并确认状态栏有eslint图标，否则检查设置或包管理器配置。
本地安装 eslint 是唯一可靠的前提
团队里有人标红、有人没反应，八成是本地没装 eslint。VSCode 的 ESLint 扩展默认只找 node_modules/.bin/eslint，全局安装（npm install -g eslint）在协作中基本等于没装——Node 版本或小版本不一致时（比如 v8.52 vs v8.56），插件可能直接 fallback 失败，且无法保证规则一致性。
必须统一执行：npm install eslint --save-dev（或 yarn add eslint -D）。验证是否就位：在项目根目录运行 npx eslint --version，有输出即成功。
- 禁止在
package.json的scripts里写"lint": "eslint ."就算完事——编辑器不读这个 - monorepo 场景下，每个 package 都要单独装
eslint，不能只在 workspace 根装 - CI 脚本也必须依赖本地
npx eslint，否则和开发环境脱节
.eslintrc.* 必须放在项目根目录且非空
ESLint 按文件路径向上查找配置，src/.eslintrc.js 对 index.js（在根目录）完全无效。把配置放错位置，等于没配。
配置文件名需匹配项目模块系统：package.json 里有 "type": "module"？那就必须用 .eslintrc.cjs 并以 module.exports = {} 导出；否则 Node 会报 Cannot use import statement。
- 空配置
{}= 零检查，至少加extends: ["eslint:recommended"] - 用 React？加
plugin:react/recommended；用 TypeScript？额外装@typescript-eslint/eslint-plugin并在extends中加@typescript-eslint/recommended - 避免在
rules里逐条关规则（如"no-console": "off"），改用overrides分场景控制，比如只对测试文件禁用
VSCode 必须打开项目根目录，状态栏图标是唯一可信信号
打开子文件夹（比如只开了 src/）会导致插件根本读不到根目录的 .eslintrc.* 和 package.json。此时编辑器一切“看起来正常”，但右下角状态栏没有 ESLint 图标——这是团队协作中最常被忽略的失效原因。
确认方式只有两个：窗口标题栏显示的是项目名（不是路径），且 资源管理器顶部显示的是项目根目录名；再看右下角状态栏：Disabled 表示被手动禁用，无图标表示未加载，有徽标 + 数字才代表正常运行。
- 若显示
Disabled，点击它 → 选Enable for Workspace - 若仍无效，检查
.vscode/settings.json或用户设置里是否有"eslint.enable": false - 多人协作时，建议在
.vscode/settings.json中显式写入"eslint.enable": true，避免依赖用户级设置
保存时自动修复需按需启用，且仅对 --fix 支持的规则生效
"editor.codeActionsOnSave": {"source.fixAll.eslint": true} 这个配置看似方便，但容易掩盖规则意图。比如 no-unused-vars 可以自动删变量，但 no-undef 就没法自动修——它需要你补定义或引入。
更稳妥的做法是限定范围："editor.codeActionsOnSave": {"source.fixAll.eslint": "explicit"}，这样只在你手动触发 Quick Fix（Ctrl+.）时才修，避免误删关键代码。
- 确保
eslint.packageManager设置为项目实际使用的包管理器（npm/yarn/pnpm），否则--fix可能找不到插件 - React / Vue 单文件组件中，若
.vue文件没被识别，检查eslint.options.extensions是否包含".vue" - 修复后仍有波浪线？运行
npx eslint --fix src/看终端报错，常是插件缺失（如eslint-plugin-vue）或解析器配置错误
团队协作中真正难的不是配通 ESLint，而是让所有人始终打开同一个根目录、始终用同一个本地版本、始终看到同一个状态栏图标。这三个“始终”缺一不可，而它们全靠约定和可视化信号来维持——别信“我这边好着呢”，只信右下角那个小图标。
