TypeScript 中 no-unsafe-declaration-merging 报错排查
记录 no-unsafe-declaration-merging 报错的含义、触发原因、排查路径和更安全的替代写法。
#tech / dev
#resource / typescript
#type / debug
#status / growing
[!info] related notes
- 所属 MOC: TypeScript MOC
- 相关概念: TypeScript 中的声明合并, TypeScript 类型检查
- 相关实践: TypeScript 中的全局声明与全局扩展
TypeScript 中 no-unsafe-declaration-merging 报错排查
现象
ESLint 提示：
Unsafe declaration merging between classes and interfaces常见触发方式是：为一个 class 再声明同名 interface，用来补事件方法或额外类型签名。
原因
这类写法的问题不在于 TypeScript 完全不支持，而在于：
- 类型补丁和运行时实现容易分离
- 类和接口的成员可能失去显式对应关系
- 团队协作时更难判断哪些能力是真的由类实现、哪些只是类型层补充
因此 @typescript-eslint/no-unsafe-declaration-merging 会把它标成有风险的模式。
排查过程
遇到这个报错时，先确认三件事：
- 这是不是 class 与同名 interface 的合并
- 合并的目的是什么：补事件签名、补静态方法，还是扩展全局
- 有没有更显式的替代方式
解决方案
更推荐的替代方式
- 直接在类体里声明重载
- 通过泛型把事件类型传进基类
- 在明确需要的地方做局部类型断言
什么情况下不该继续硬压
如果只是为了让编辑器更聪明，但引入了隐式类型补丁，通常更值得把类型关系写显式，而不是继续依赖 class/interface 同名合并。
回归验证
修完后应确认：
- ESLint 不再报
no-unsafe-declaration-merging - 编辑器仍然保留需要的类型提示
- 运行时行为没有被误解为“类型补丁自动生成实现”