ESLint error 常见错误和解决步骤

ESLint 报错最容易被当成“烦人的拦路石”。新手为了让 build 通过，可能直接关规则、删脚本、批量加 eslint-disable。短期看起来顺了，长期会让项目更难维护。

完整判断见 ESLint error 要不要直接关闭，逐项核对见 ESLint error 处理检查清单。

适合谁

适合已经尝试修 lint，但越修越乱的新手。你可能不知道规则名代表什么，也可能害怕改代码影响页面。

也适合准备接“修 lint 报错”任务的人。ESLint 报错可以接，但要有诊断、修复和验证记录。

不适合谁

不适合把“没有 lint 报错”当作唯一目标的人。没有报错可能是因为问题被隐藏，不代表代码更可靠。

也不适合没有客户确认就修改全局配置或 CI 规则的人。团队项目里的 lint 规则通常是协作契约。

风险提醒

最危险的不是单条规则，而是无记录地扩大禁用范围。一个文件顶部的禁用可能掩盖十几个问题；一个全局配置改动可能影响整个仓库。

如果客户项目涉及团队规范、CI、部署门禁或代码所有权，先暂停并确认范围。不要把“我先关掉检查”当成服务方案。

具体步骤

错误一：全局关闭 ESLint

全局关闭会让所有规则失效。你可能解决了当前报错，也同时失去了其他提醒。

更稳做法：先处理具体文件和具体规则。

错误二：批量加禁用注释

批量加 eslint-disable 看起来快，但后续没人知道哪些是真例外，哪些只是懒得修。

更稳做法：只在小范围、单条规则、带原因说明时使用。

错误三：忽略 Hook 规则

React Hook 相关规则经常和状态同步、闭包、依赖数组有关。随手关闭可能导致页面行为不稳定。

更稳做法：先理解依赖关系，再调整逻辑。

错误四：删除未使用变量但不看逻辑

未使用变量有时说明功能没接完。直接删除可能让你错过真实问题。

更稳做法：判断变量是多余代码，还是本该参与逻辑。

错误五：只跑 build 不跑 lint

有些项目 build 不会覆盖全部 lint 检查。只跑 build 可能漏掉团队要求。

更稳做法：按项目脚本运行 lint、build，必要时加 test。

推荐解决顺序

先保存完整 lint 输出，再按规则名分组。能修代码就修代码，不能修时再看配置是否合理。确实需要例外时，用最小范围禁用，并写清原因。最后运行验证命令，看 diff 是否只触及相关文件。

如果已经改乱，先停下来整理时间线：原始报错、尝试动作、当前剩余错误、哪些规则被改过。这样才能恢复判断。

复盘时看什么

复盘重点是范围有没有扩大。你是否从一个文件的问题改成了全局配置？是否从一条规则变成禁用整个文件？是否为了当前任务影响了无关模块？这些都要写进记录。

做项目时，复盘还能保护你自己。客户之后问为什么还有其他 lint 报错时，你可以说明本次只处理了哪些规则和文件，哪些不在范围内。

怎么恢复判断

如果已经加了很多禁用注释，先不要继续加。第一步是列出所有新增的禁用位置，按规则名分组。第二步是判断哪些可以直接修代码，哪些需要配置确认，哪些是真正的临时例外。第三步是逐个恢复验证。

恢复时不要一次删掉所有禁用。每次只处理一个文件或一类规则，删掉后运行 lint 和 build。这样能知道哪条禁用还必要，哪条只是遮住了可以修的代码。

如果客户项目里已经存在大量历史禁用，本次任务只处理新增范围。不要把全仓库历史债务都揽成一个小单。

给客户怎么说明

可以把说明写成三句话：第一句说明本次报错来自哪些规则；第二句说明优先修代码而不是关闭检查；第三句说明是否存在需要确认的配置或团队规则。这样的说明足够短，但能让客户知道你不是随手处理，而是在控制范围。

如果你确实需要保留一处局部禁用，说明里要写清楚位置、规则名、原因和移除条件。不要只写“已处理”，因为客户或后续维护者看不到判断过程。更稳的写法是：某一行因为第三方类型或迁移期代码暂时不能直接改，本次只对这一处规则做局部例外，后续满足条件后再移除。

遇到 CI 和本地结果不一致时，也要把它放进说明里。比如本地 Node 版本、包管理器、锁文件、CI 脚本和团队配置可能不同。此时合理交付不是擅自改门禁，而是列出差异并请客户确认下一步范围。这样既能保护项目，也能保护你的项目边界。

CTA：下一步

把当前 ESLint 报错写成五项：规则名、文件行号、错误原因、修复方式、验证命令。需要模板时去 模板库，需要拆日志时用 报错解释器。

免责声明

本文是学习和排查流程，不构成法律、财务、安全或职业承诺。实际处理 ESLint 需要结合项目规则、团队规范、CI 配置、真实代码和客户授权人工判断。