ESLint error 处理检查清单

ESLint 报错处理不要从关闭规则开始。完整说明见 ESLint error 要不要直接关闭。这篇是可以复制到项目诊断表里的检查清单。

适合谁

适合遇到 lint 报错、部署前检查失败、CI 阻塞的新手。你可以用它判断该修代码、改配置，还是记录少量例外。

也适合项目前做诊断。清单能帮你解释“为什么不建议直接关掉 ESLint”。

不适合谁

不适合在客户项目里批量关闭规则、删除 lint 脚本、跳过 CI 的新手独立操作。项目规范可能来自团队约定，不能随意改。

也不适合只想让 build 通过而不关心代码质量的人。隐藏报错不是修复。

风险提醒

全局禁用 ESLint 可能掩盖真实 bug。局部禁用也要有理由、范围和记录。客户项目里，涉及全局配置、CI 配置、团队规则时，先写入待确认事项。

不要把“没有报错”当成唯一目标。目标是代码能解释、能验证、能维护。

具体步骤

1. 报错记录

• 运行命令：
• 完整报错：
• 文件路径：
• 行号：
• 规则名：

没有规则名，就很难判断该怎么修。

2. 规则分类

• 格式或风格：
• 未使用变量：
• React Hook：
• 可访问性：
• 异步错误：
• 导入路径：
• 项目自定义规则：

不同规则对应不同风险。

3. 优先修代码

• 删除未使用变量。
• 修正导入。
• 补齐 Hook 依赖。
• 调整逻辑结构。
• 补可访问性标签。

能修代码就不要先禁用。

4. 判断配置

• 当前规则是否适合项目技术栈。
• 是否是迁移期遗留问题。
• 是否与框架推荐冲突。
• 是否需要团队确认。

配置调整比单行修复影响更大。

5. 局部禁用条件

• 是否只影响一行或一个小块。
• 是否只禁用一条规则。
• 是否有注释说明原因。
• 是否有后续清理计划。

不满足这些条件时，不建议禁用。

6. 验证

• 重新运行 lint。
• 运行 build。
• 检查相关页面或测试。
• 看 diff 是否只改了相关文件。

验证结果要写进记录。

结论怎么写

结论可以分三类：已修代码、需调整配置、需客户或团队确认。不要只写“已关闭 ESLint”。如果用了局部禁用，要写明原因和范围。

最低交付记录包括：规则名、文件、修复方式、验证命令、验证结果、剩余风险。这样客户能看懂你做的是修复，不是遮住报错。

禁用记录怎么写

如果确实使用了 eslint-disable，单独写一条记录。记录包含：禁用位置、规则名、为什么不能直接修代码、影响范围、后续移除条件。没有这五项，就先不要提交禁用。

示例思路是：某个第三方库类型不完整，当前只能对单行禁用一条规则；后续升级类型包或替换 API 后再移除。这样的记录比“先关掉再说”清楚得多。

本地和 CI 怎么对齐

有些项目本地 lint 通过，CI 仍失败。此时要检查 Node 版本、包管理器、锁文件、lint 命令和 CI 是否运行了额外脚本。不要只看本地结果。

如果 CI 规则由客户团队维护，先记录差异，让客户确认是否允许改配置。新手不应该为了通过一次检查就修改团队门禁。

最低交付记录

最低交付记录至少包含六项：原始命令、规则名、影响文件、处理方式、验证命令、剩余风险。原始命令用来说明你复现的是同一个问题，规则名用来定位处理方向，影响文件用来控制范围，处理方式说明你是修代码、改配置还是加入局部例外，验证命令说明结果是否可复查，剩余风险则告诉客户还有哪些判断没有完成。

如果处理的是客户项目，还要单独写是否修改了全局配置、是否加入了局部禁用、是否影响 CI。全局配置和 CI 门禁属于团队协作边界，不适合在没有确认的情况下直接改。局部禁用即使只影响一行，也要写清楚规则名和原因，方便后续维护者判断是否可以移除。

交付记录不需要写成长报告，但要能回答三个问题：为什么报错、这次具体改了什么、怎么证明没有把范围扩大。只要这三个问题说清楚，ESLint 报错处理就更像一次可复查的工程修复，而不是临时把检查压下去。

CTA：下一步

复制这份清单，先填规则名、文件行号和报错命令。需要拆日志时用 报错解释器，需要估算诊断时间时用 报价计算器。

免责声明

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