ESLint 开发问题总结

ESLint 配置不生效问题

捣乱的插件

现象： 无论怎么在 rules 里写 "error"，终端和编辑器死活只显示 Warning（黄色），不报错（红色）。 原因：eslint-plugin-only-warn真相：

• 你的共享配置（packages/eslint-config）里偷偷装了这个插件。
• 它的作用： 强制把所有 Error 降级为 Warning。
• 教训： 排查规则不生效时，先看看 package.json 里有没有这种“全局修改型”的插件。

三大“隐形干扰源”

A. Next.js 的“溺爱”模式

• 现象： 终端运行 pnpm lint 是 Warning，但你觉得应该是 Error。
• 原因：next lint 命令为了不阻断开发（Build），会自动把 no-unused-vars 等非致命错误降级为 Warning。
• 对策： 想要看真实的 ESLint 结果，请用原生命令：npx eslint app/page.tsx。

B. VS Code 的“老旧记忆” (缓存)

• 现象： 终端 (pnpm lint) 已经变红了（Error），但 VS Code 编辑器里还是黄的（Warning）。
• 原因： VS Code 的 ESLint 服务启动后会把配置加载到内存，你改了配置文件它不知道。
• 对策： 改完配置，必须 F1 -> Restart ESLint Server，甚至 Reload Window。

C. Flat Config 的“权重游戏”

• 现象： 你的规则写了，但被别人的规则覆盖了。
• 原因： ESLint 9 (Flat Config) 严格遵循 “数组后发优势” 和 “文件范围优先级”。
• 对策：
  • 想要覆盖规则？把你的对象放在数组的 最后面。
  • 想要绝对霸权？加上 files: ["**/*.ts"] 明确指定生效范围，权重更高。

Monorepo 的运作机制

问题： 为什么 App 能读到 Packages 里的配置？编辑器怎么知道要去哪里找？

• 物理连接 (Symlink)： 包管理器 (pnpm) 会在 node_modules 里创建软链接，指向 packages/eslint-config。所以 import ... from "@repo/..." 实际上读的是你硬盘上的源码。
• 逻辑导航 (VS Code)：.vscode/settings.json 里的 "eslint.workingDirectories": [{ "mode": "auto" }] 告诉编辑器：“别只看根目录，进到 apps/web 里去工作”。

终极调试口诀 (Cheatsheet)

下次再遇到 “配置了没生效” 的情况，按这个顺序查：

1. 查插件： VS Code 装 ESLint 插件了吗？开启了吗？
2. 查死活： 运行 npx eslint app/page.tsx。
   • 如果终端没报错：说明配置没写对，或者被 only-warn 这种插件劫持了。
   • 如果终端报错了：说明配置是对的，问题在编辑器。
3. 查缓存：F1 -> Restart ESLint Server。
4. **查忽略：**是不是被 .next 或 dist 目录挡住了？（检查 ignores 配置）。
5. 查位置： 配置文件必须在项目根目录，不要为了整洁把它藏到子文件夹里。

**总结一句话：**代码配置 (config) 决定“判刑结果”，VS Code 插件决定“是否显示”，而命令行 (npx eslint) 才是永远不说谎的法官。