如何为第三方JavaScript模块渐进式添加TypeScript类型声明

你遇到的TS2305报错本质原因是：当你编写带具体导出的declare module 'third-party'声明块时，TypeScript默认将其视为该模块的完整类型定义，所有未在声明块中列出的导出都会被判定为不存在。
要实现「已声明导出走严格类型校验、未声明导出暂不做类型约束」的渐进式迁移效果，只需要在模块声明块中增加兜底的索引签名即可，修改后的类型声明文件写法如下：

// types.d.ts 
import type { ReactNode } from 'react';

declare module 'third-party' {
  // 已补全类型的导出，会正常做类型校验
  export type FirstComponentProps = {
    name?: string;
  }
  // 注意：类型声明中用冒号标注类型，不要用等号赋值
  export const FirstComponent: (props: FirstComponentProps) => ReactNode;

  // 关键兜底：所有未显式声明的导出，类型默认为any，不会触发不存在导出的报错
  [key: string]: any;
}

方案说明 #

• 该写法下，你显式声明的FirstComponent、FirstComponentProps会按照定义的规则做严格类型校验，和你预期的效果一致。
• 其余未在声明块中列出的导出（比如示例中的SecondComponent）会被自动识别为any类型，不会抛出TS2305错误，导入使用时暂不做类型约束。
• 后续你需要为其他导出补充类型时，只需要在同一个declare module块中追加对应的类型声明即可，新追加的导出会自动覆盖兜底的any类型，获得严格类型校验能力，不需要修改其他已有配置。

版本兼容提示 #

如果你的项目使用TypeScript 5.1及以上版本，还可以使用更语义化的语法代替字符串索引签名，在声明块末尾添加如下代码即可实现完全相同的效果：

export * as any;

内容的提问来源于stack exchange，提问作者gerrod