TrueGrowth/docs/TSC_REGRESSION_LESSONS.md

TypeScript 回归经验

2026-04-24：库级 tsc 不能长期带病运行

这次 packages/drawnix 的库级 tsc 报错，问题本身并不复杂，但暴露了一个典型风险：

• 缺模块引用长期残留
• 公共类型名已经改了，旧代码还在用
• 日志/服务 API 签名变了，调用点没跟着更新
• 小组件里 JSX、useEffect 返回值、泛型这些小错误长期没人收口

单个问题都不大，但堆起来后会让库级校验逐渐失真，最终变成：

• 真回归和旧债混在一起
• 新问题一出现，很难第一时间判断是不是自己引入的

这次固化出来的规则

1. 失效引用要尽快删或改

如果模块已经不存在：

• 要么改到现有实现
• 要么删掉测试/入口里的旧引用

不要让“已经找不到的 import”长期存在。

2. 类型重命名后，兼容层要明确

像 MCPContentItem -> MCPContent 这种类型漂移，要么统一升级所有调用点，要么补清晰的兼容层。
不要让旧名字零散残留在边角文件里。

3. 日志 API 这类基础设施变更，要优先清理调用点

基础服务的签名一旦变化，边缘模块最容易悄悄积累报错。
这类问题应该尽快收口，否则以后每次跑 tsc 都会被旧错误淹没。

4. 共享 hook 和测试入口也要纳入校验面

这次有些错误来自：

• 共享 hook
• 测试组件
• 非主路径服务

它们平时不一定常跑，但只要进了库级编译范围，就必须保持可编译。

适合固化的检查清单

• 新增或重命名公共类型后，是否全仓搜索并清理旧引用？
• 删除模块后，相关测试组件和调试入口是否也同步处理？
• 基础日志/服务 API 变更后，是否及时修完所有调用点？
• 库级 tsc 是否保持长期为 0，而不是“先放着以后再说”？