TypeScript中如何为本地JS函数配置使用.d.ts类型声明文件

给第三方npm包和本地相对路径导入的JS模块写类型声明的规则存在区别：你之前在typeRoots下用declare module "包名"的写法，仅适用于裸说明符导入的第三方包（不带.//../路径前缀的导入，比如import xxx from 'random-joke'），本地相对路径导入的JS模块不会走这个全局声明检索逻辑，所以之前的写法不生效。

以下是两种符合TS规范的配置方案，不需要开启allowJs: true：

方案1：同名邻接声明文件（官方推荐，零额外配置） #

直接在目标JS文件的同级目录，创建和JS文件同名、后缀为.d.ts的声明文件，TS会自动关联同路径同名的声明文件作为对应JS的类型定义，不需要修改tsconfig配置。
针对你的modules/utils.js，直接在同目录创建modules/utils.d.ts即可：

// modules/utils.d.ts
export function sum(a: number, b: number): number;
export function power(a: number, b: number): number;
export function multiply(a: number, b: number): number;

写完后正常导入./modules/utils就能获得完整类型提示。

方案2：集中管理本地模块声明 #

如果不想把声明文件和JS文件放在一起，可以集中存放所有本地模块的类型声明：

• 新建专门存放本地类型的目录，比如src/types
• 修改tsconfig.json，确保该目录被TS纳入检索范围：

{
  "compilerOptions": {
    // 其余原有配置保持不变，不需要开启allowJs
    "typeRoots": ["./node_modules/@types", "./src/types"]
  },
  "include": ["src/**/*", "src/types/**/*"]
}

• 在类型目录下新建声明文件（比如local-modules.d.ts），注意declare module后必须写和import语句完全一致的相对路径：

// src/types/local-modules.d.ts
declare module './modules/utils' {
  export function sum(a: number, b: number): number;
  export function power(a: number, b: number): number;
  export function multiply(a: number, b: number): number;
}

注意：该方案要求declare module后的路径和import时写的路径完全匹配，路径前缀、文件名不一致都会导致识别失败，维护成本更高，非必要优先选方案1。

报错说明 #

• ts(6133) 'sum' is declared but its value is never read：该报错和类型声明无关，是TS检测到你导入了sum但没有实际调用，在代码中使用sum（比如console.log(sum(1,2))）后报错会自动消失。
• Could not find a declaration file for module './modules/utils'：按照上述任意一种方案配置正确的d.ts文件后即可消除。allowJs: true的作用是让TS直接编译、检查JS文件内容，本质是绕过了类型声明校验，不是补本地JS类型的规范方案。

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