# 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，而不是“先放着以后再说”？