如何修正并扩展第三方npm包的TypeScript类型声明？

核心思路：用TypeScript模块扩展（Module Augmentation）实现类型修正与扩展 #

直接重写整个模块类型会触发重复声明错误，TypeScript允许通过模块扩展机制，在保留原有类型的基础上，合并或覆盖错误/缺失的类型定义。

步骤1：确保自定义类型目录被TS识别 #

修改tsconfig.json，让TypeScript能读取你的自定义类型文件：

{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./src/@types"],
    "include": ["src/**/*", "src/@types/**/*"]
  }
}

步骤2：编写正确的模块扩展代码 #

假设目标npm包名为target-package，在src/@types/index.d.ts中编写以下代码（根据原类型结构调整）：

情况1：修正接口属性类型 + 扩展字符串字面量类型

// 必须确保文件是模块环境，无import/export时添加空导出
export {};

declare module 'target-package' {
  // 修正Profile.Information的name类型（自动合并原有属性）
  interface Profile {
    Information: {
      name: string; // 覆盖原错误的number类型
    };
  }

  // 扩展Hobbies类型，添加缺失的选项
  import type { Hobbies as OriginalHobbies } from 'target-package';
  type Hobbies = OriginalHobbies | 'running' | 'singing';
}

情况2：原Hobbies是枚举类型的扩展方式

export {};

declare module 'target-package' {
  const Hobbies: {
    // 保留原枚举值，比如原有'reading'
    reading: 'reading';
    // 添加新选项
    running: 'running';
    singing: 'singing';
  };

  // 重新推导Hobbies类型
  type Hobbies = (typeof Hobbies)[keyof typeof Hobbies];
}

步骤3：解决编译与智能提示问题 #

• 重启VS Code的TypeScript服务：按Ctrl+Shift+P，选择「TypeScript: Restart TS Server」，确保智能提示更新
• 运行tsc --noEmit检查编译错误，若仍有冲突，检查是否重复声明了非接口/命名空间的顶级类型

注意事项 #

• 若原包类型是全局声明（非模块），改用全局扩展：

declare global {
  interface Profile {
    Information: {
      name: string;
    };
  }
  type Hobbies = 'reading' | 'running' | 'singing';
}
export {};

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