发现第三方声明文件错误怎么办？含NPM及DefinitelyTyped场景

我来帮你理清楚遇到TypeScript声明文件错误时的处理思路，分三种场景逐个说清楚：

如果是你安装的NPM包自己包含了.d.ts声明文件，但内容有错误，按这个流程来：

• 先确认问题：先排查下是不是自己的代码写法有问题，比如调用API时参数类型传错了，确认确实是声明文件和实际包的API不符
• 优先提交修复PR：找到这个包的GitHub仓库，fork一份到自己账号下，修改对应的.d.ts文件，然后提交PR给原仓库。这样不仅能解决自己的问题，还能帮到其他用户，等官方合并后直接更新包就能彻底解决
• 临时应急方案：
  • 用// @ts-ignore跳过单个错误行，但这只是权宜之计，容易掩盖其他问题，不推荐长期用
  • 用declare module局部覆盖错误的类型定义，比如在自己的项目里写一个小的声明文件，修正有问题的接口或类型
  • 复制错误的.d.ts到本地项目（比如src/types/fixed/xxx.d.ts），修改后通过tsconfig.json配置让TypeScript优先读取这个本地文件（具体配置看后面场景3）

如果错误的声明文件是@types/xxx这类包，也就是社区维护的DefinitelyTyped仓库提供的，处理方式略有不同：

• 先核对版本：有时候是因为@types/xxx的版本和你实际安装的xxx包版本不匹配导致的，比如你装了xxx@2.x，但@types/xxx还是1.x的定义，这种情况可以尝试安装对应版本的@types/xxx（比如npm install @types/xxx@2.x --save-dev）
• 提交修复到DefinitelyTyped：如果是类型定义本身有错误，去DefinitelyTyped的GitHub仓库找到对应types/xxx目录，fork后修改.d.ts文件，提交PR。官方审核通过后，新的@types/xxx版本会发布到npm，你更新就能解决
• 临时应急：同样可以用类型扩展（Type Augmentation）来修正错误的类型，或者把修改后的.d.ts复制到本地，通过tsconfig配置让TypeScript优先读取（见场景3）

不想直接改node_modules里的文件（毕竟修改不会被版本控制保留），可以按这个步骤来：

1. 复制并修改声明文件：把node_modules里有问题的.d.ts文件复制到你项目的某个目录，比如src/types/custom，然后在这个本地文件里修正错误
2. 修改tsconfig.json配置，让TypeScript优先读取本地的文件，有几种方式：
   • 方式一：用paths映射模块
     在compilerOptions里添加paths配置，把目标模块指向你本地的声明文件：

     {
       "compilerOptions": {
         "baseUrl": ".",
         "paths": {
           "xxx": ["./src/types/custom/xxx.d.ts"],
           "@types/xxx": ["./src/types/custom/xxx.d.ts"]
         }
       }
     }
     

     注意要设置baseUrl，否则paths可能不生效
   • 方式二：调整typeRoots优先级
     如果是@types类的声明文件，可以修改typeRoots，把你的本地类型目录放在前面：

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

     这样TypeScript会先在./src/types/custom里找类型定义，找不到再去node_modules/@types
   • 方式三：确保本地声明文件被include
     把你的本地类型目录加入include数组，确保TypeScript能扫描到：

     {
       "include": ["src/**/*", "src/types/custom/**/*"]
     }
     

总结一下，优先给原仓库提交PR是最彻底的解决方式，既能帮到社区也能一劳永逸；临时方案则可以通过本地修改声明文件+tsconfig配置来实现，完全不用碰node_modules，修改也能被Git跟踪保留。

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