ESLint配置文件未生效的首要原因是未被正确加载，需确认是否位于项目根目录或工作区顶层，并通过ESLint: Show Output Channel验证路径；其次检查导出格式、Node版本及Flat Config启用状态。
ESLint 配置文件没生效？先确认 .eslintrc.js 是否被正确加载
VSCode 里 ESLint 插件标红但规则不触发，90% 是配置文件没被识别。它不会自动找任意路径下的 .eslintrc.js，只认项目根目录或当前打开文件所在工作区的顶层目录。
- 打开命令面板（
Ctrl+Shift+P），运行ESLint: Show Output Channel，看输出里有没有 “Using config file” 路径 —— 如果显示的是~/.eslintrc.js或根本没出现路径，说明没加载到项目级配置 -
.eslintrc.js必须导出一个对象，且不能有语法错误（比如用import但没配type: "module"）；Node.js 版本低于 14.18 时，export default会直接静默失败 - 如果项目用了
eslint.config.mjs（Flat Config），需在 VSCode 设置中显式开启："eslint.useFlatConfig": true，否则插件完全忽略该文件
editor.formatOnSave 和 eslint.format.enable 别混用
这两个设置作用完全不同，但名字太像，容易误配导致格式化失效或冲突。
-
editor.formatOnSave是 VSCode 全局开关，控制“保存时是否触发格式化”，必须为true才可能生效 -
eslint.format.enable是 ESLint 插件自己的开关，只对 JavaScript/JSX 文件起作用；设为false时，即使editor.formatOnSave开着，ESLint 也不会参与格式化 - 若同时装了 Prettier，建议关掉
eslint.format.enable，改用"editor.defaultFormatter": "esbenp.prettier-vscode"+"eslint.format.enable": false，避免规则打架
团队规范落地难？把规则写进 package.json 的 scripts 里
光靠 VSCode 设置无法保证 CI/CD 或新成员本地环境一致。真正能兜底的方式是把检查逻辑固化到 npm script 中。
- 在
package.json里加："lint": "eslint . --ext .js,.jsx,.ts,.tsx"，再配合"precommit": "npm run lint"（需 husky） - VSCode 插件只负责编辑时提示，而
npm run lint是唯一可信的“最终校验”——CI 流水线、PR 检查、本地提交前都走这一套 - 不要在
.eslintrc.js里写console相关规则（如"no-console": "warn"）然后指望开发者自觉修复；直接加--fix参数并放进 script："lint:fix": "eslint . --ext .js --fix"
自定义规则开发时，vscode.languages.registerDocumentSemanticTokensProvider 不是必需项
很多教程一上来就推 Semantic Tokens，其实 95% 的代码规范检查（比如禁用 eval、检查变量命名）根本不需要它。
- 简单字符串扫描：用
vscode.workspace.onDidChangeTextDocument监听变化，配合document.getText()+ 正则即可覆盖大部分静态检查场景 - 需要 AST 级别的精确定位（比如只报错函数参数名，不报错字符串里的同名文本），才用
typescript或acorn解析，再结合vscode.languages.createDiagnosticCollection推送Diagnostic - 别提前引入
vscode-languageclient或 LSP —— 除非你要支持跨文件跳转、重命名重构等 IDE 级功能，否则纯客户端插件更轻、启动更快、调试更直接
javascript 和 javascriptreact 语言模式，如果你的文件后缀是 .mjs 或 .cjs，或者用了 astro、svelte 这类混合语法，必须手动在设置里补全："eslint.validate": ["javascript", "javascriptreact", "typescript", "astro"]。漏掉这一条，整个文件就等于没检查。 
