重构shi山工程，却遇到全局的1000+ts问题...

起因

我接到组里的任务，需要迁移包，但是涉及的页面基本涵盖全站了，所以我怕测试测的时候会有遗漏，以及有些隐含的错误导致上线后爆炸，所以我就执行了

npx tsc --noEmit --watch false

然后我就得到了如下：

---

🔧 一、​​错误标记与基线建立（优先冻结历史问题）​​

1. ​​统一抑制历史错误​ ​

   使用 suppress-ts-errors 工具批量添加注释，将现有错误标记为"已知问题"，避免干扰新代码检查：

   npx suppress-ts-errors --mode baseline

   • 该工具会自动在错误位置插入 // @ts-expect-error 或 // @ts-ignore 注释，并附带错误代码说明。
   • ​优势​：将历史错误转化为显式忽略清单，后续新增错误会因无抑制注释而暴露。

2. ​​按需使用高级抑制策略​​

   • ​文件级忽略​ ：对错误密集且暂不重构的文件，在文件顶部添加 // @ts-nocheck。
   • ​目录级配置​ ：通过 tsconfig.json 的 exclude 字段排除非核心模块的检查（慎用）。

---

🛡️ 二、​​重构安全保障策略​​

1. ​​隔离重构范围​​

   • 使用 // @ts-expect-error 而非 @ts-ignore：前者要求后续修复错误后必须移除注释，否则会报错，避免遗忘。

   • ​​示例​​：

     // @ts-expect-error TS2345: 历史类型不匹配，待重构
     const value: string = legacyFunctionReturningNumber();

2. ​​增量编译与防御性编程​​

   • ​​检查范围聚焦​​：仅检查修改的文件，降低历史错误干扰：

     npx tsc --noEmit --incremental --watch false

   • ​​防御性类型保护​​：对不确定的第三方库或遗留代码，使用类型断言和守卫函数：

     function isError(value: unknown): value is Error {
       return value instanceof Error || 
              (!!value && typeof value === 'object' && 'message' in value);
     }
     try { ... } 
     catch (e) {
       if (isError(e)) console.error(e.stack); // 安全访问属性
     }

---

🔍 三、​​渐进修复策略​​

1. ​​错误分类与优先级排序​​

   ​​错误类型​​	​​处理策略​​	​​优先级​​
   安全修复（如类型断言）	立即修复	⭐⭐⭐
   复杂重构（接口调整）	标记后纳入迭代计划	⭐⭐
   第三方库类型缺失	补充 @types/ 包或声明文件	⭐

2. ​​分阶段修复流程​​

   graph TD
     A[抑制所有历史错误] --> B[开启严格模式检查新代码]
     B --> C[按模块逐个修复历史错误]
     C --> D[移除已修复模块的抑制注释]

   • 每修复一个模块，移除对应文件的抑制注释，确保进度可视化。

---

⚙️ 四、​​工具链与自动化支持​​

1. ​​ESLint 集成​ ​

   配置规则 @typescript-eslint/ban-ts-comment，限制抑制注释滥用：

   {
     "rules": {
       "@typescript-eslint/ban-ts-comment": ["error", {"ts-expect-error": false}]
     }
   }

   • 允许 @ts-expect-error 但禁止 @ts-ignore，提升代码质量。

2. ​​预提交钩子检查​ ​

   通过 husky + lint-staged 确保新增代码无编译错误：

   "lint-staged": {
     "*.ts": "tsc --noEmit --incremental"
   }

---

👥 五、​​团队协作与知识管理​​

1. ​​错误文档化​ ​

   使用 suppress-ts-errors 生成错误报告，关联到任务管理系统（如Jira）：

   npx suppress-ts-errors --report > technical-debt.md

2. ​​定期技术债务清理​ ​

   将历史错误修复纳入迭代计划，每周分配固定工时处理。

---

💎 总结

​​核心思路​ ​：

✅ ​​先冻结​ ​（抑制历史错误）→ ​​再隔离​ ​（确保新代码零错误）→ ​​渐进修复​​（分模块推进）。

通过此方案可以在重构过程中精准识别新引入的错误（历史错误已被标记），同时通过类型守卫和自动化工具降低风险。对于遗留错误，建议按业务影响和修复成本制定优先级，避免陷入"全量修复"的泥潭。