启用checkJs时TypeScript .d.ts声明未被检测的问题排查

你的核心问题是：在JavaScript项目中，index.d.ts里的全局函数类型声明没有对index.js中的同名函数实现进行类型检查，而其他类型关联方式（导入、JSDoc）正常工作。

原因 #

TypeScript在处理JavaScript文件时，会优先使用文件内的实际变量/函数定义，而非全局.d.ts中的声明。当index.js里定义了const func = () => {}时，这个局部定义会覆盖全局.d.ts中的同名声明，导致类型检查不生效。

解决方案 #

要让全局.d.ts的声明约束JavaScript文件中的同名函数，需要将.d.ts文件转为模块类型的全局声明，具体步骤如下：

1. 修改index.d.ts，添加模块导出标识并使用declare global包裹类型声明：

declare global {
  function func(): () => 42;
}

// 这一行是关键，将文件标记为模块，否则global声明不生效
export {};

2. 保留现有jsconfig.json配置即可，你的配置已经开启了checkJs和strict，这些是类型检查的必要条件。

修改后，TypeScript会将index.js中的func与全局声明的类型绑定，此时如果func的实现不符合声明的类型（比如返回空函数而非返回42的函数），就会触发类型错误提示。

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