ESLint error 要不要直接关闭

ESLint 报错不应该默认直接关闭。它可能只是格式、未使用变量、Hook 依赖、可访问性、导入顺序，也可能是在提醒你代码有真实风险。新手最常见的误区，是为了让 npm run build 或部署通过，直接关掉规则、删除配置，或者在整份文件顶部加大范围禁用。

更稳的顺序是：先读报错里的规则名、文件和行号，再判断是代码可以修、规则需要配置、还是确实存在少量例外。只有解释清楚原因、范围很小、验证通过时，才考虑局部禁用。检查清单见 ESLint 报错处理检查清单，误区见 ESLint 报错常见错误和解决步骤。

适合谁

适合遇到 eslint .、next lint、CI lint、部署前 lint 报错的新手。你可能不知道某条规则是什么意思，也可能担心修完后页面行为改变。

也适合准备接“修 lint 报错”小单的人。ESLint 问题可以做成低风险诊断，但前提是你能保存报错、解释规则、运行验证命令，并写清楚修改范围。

不适合谁

不适合为了省时间直接关闭整个 lint 流程的人。全局关闭检查可能让后续代码质量、可访问性、Hook 调用和潜在 bug 都失去提醒。

也不适合在客户项目里没有说明就批量加 eslint-disable 的人。客户要的是可维护代码，不是把报错藏起来。

风险提醒

关闭 ESLint 的风险是“检查没了，问题还在”。比如 React Hook 依赖错误可能导致页面状态不同步；未处理的 promise 可能导致失败被吞掉；无障碍规则可能影响用户体验；未使用变量可能说明逻辑没有接上。

客户项目里，如果 lint 是 CI、部署或团队规范的一部分，不要私自修改全局配置。涉及仓库规则、CI 配置、团队代码规范时，先记录为待确认事项。

具体步骤

1. 保存完整报错。记录命令、文件、行号、规则名和错误信息。
2. 判断规则类型。是格式、类型、React Hook、安全、无障碍、导入、未使用代码，还是项目自定义规则。
3. 优先修代码。能删除未使用变量、补依赖、拆函数、修导入，就不要先禁用规则。
4. 判断配置是否合理。如果规则和项目技术栈不匹配，再考虑调整配置，但要写清原因。
5. 如需禁用，范围要小。优先单行、单条规则、带解释，不要整文件或全项目禁用。
6. 运行验证。修完后跑 lint、build，必要时检查页面或测试。
7. 写交付记录。说明报错、修改方式、验证结果和剩余风险。

什么时候可以局部禁用

局部禁用不是绝对不能用，但必须有理由。比如第三方库类型不完整、迁移期临时兼容、规则误判、自动生成代码无法修改，这些场景可以考虑单行或小范围例外。

即便如此，也要留下说明。比如写明为什么暂时禁用、何时可以移除、影响范围是什么。没有说明的禁用，很容易变成长期技术债。

什么时候不该禁用

如果报错指向真实逻辑问题，就不该禁用。比如 Hook 依赖缺失、数组 key 不稳定、异步错误未处理、变量未使用但本来应该参与逻辑、可访问性标签缺失。这些问题应该修代码。

如果只是为了让部署通过，也不该禁用。部署通过不是唯一目标，交付要能解释、能复查、能维护。

项目前怎么处理

把任务先定义为“lint 报错诊断”。交付内容包括规则名、影响文件、原因判断、修复建议和验证命令。只有客户确认允许修改代码或配置时，才进入修复。

需要客户沟通稿时，可以用 Proposal 生成器 起草确认问题；需要估算诊断和验证时间时，用 报价计算器。

处理结论怎么分级

处理完 ESLint 报错后，建议把结论分成四级。第一级是已修代码，例如删除多余变量、补齐依赖、修正导入。第二级是需调整配置，例如规则和项目技术栈不匹配，但这类改动要写清影响范围。第三级是临时例外，例如第三方类型不完整，只能局部禁用一条规则。第四级是需客户或团队确认，例如 CI 规则、全局配置、历史遗留规则。

这种分级能避免把所有动作都写成“已解决”。如果你只是加了一条局部例外，就不能说代码问题已经完全修好；如果你改了全局配置，也要让客户知道影响的不止当前文件。

交付记录怎么写

交付记录至少写：原始规则名、影响文件、处理方式、是否禁用规则、验证命令、剩余风险。客户不一定要看全部技术细节，但你自己必须能复盘。

如果使用了局部禁用，记录里要写原因。比如“第三方库类型声明缺失，临时禁用一行，后续升级依赖后可移除”。没有原因的禁用，会让后续维护者很难判断是否可以删除。

CTA：下一步

复制 ESLint 的完整报错，先找规则名和文件行号。不要先关规则。需要拆日志时，用 报错解释器；需要记录流程时，从 模板库 下载项目诊断表。

免责声明

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