如何在VSCode中为带JSDoc无TS类型的npm包启用智能提示

当使用这类npm包时，TypeScript默认会抛出如下ts(7016)报错：

Could not find a declaration file for module '...'. '...' implicitly has an 'any' type.
  Try `npm i --save-dev @types/xxx` if it exists or add a new declaration (.d.ts) file containing `declare module 'xxx';`

常规的手动写空声明文件、等包维护者生成d.ts的方案都存在明显缺陷：空声明会丢失所有类型提示，手动补全类型成本极高，而官方的JS生成d.ts流程面向包维护者设计，不适合普通使用方。
以下是作为包消费方可落地的最佳方案，不需要修改依赖源码，就能拿到基于原生JSDoc的完整IntelliSense提示：

首选方案：修改TS配置直接解析包内JSDoc #

这是成本最低、维护性最好的方案，不需要额外生成文件，直接让TS编译器读取npm包自带的JS和JSDoc内容提供提示：

• 打开项目根目录的tsconfig.json文件
• 在compilerOptions字段下添加两个配置：

  {
    "compilerOptions": {
      "allowJs": true,
      "maxNodeModuleJsDepth": 3
    }
  }
  

  • allowJs: true：允许TS编译器直接解析JS文件，识别其中的JSDoc类型注释
  • maxNodeModuleJsDepth: 3：控制编译器递归解析node_modules依赖的深度，设置为3-5即可覆盖绝大多数包的导出结构，数值过大会拖慢项目编译速度
• 如果不想全局放开所有node_modules包的JS解析权限，可以搭配typeRoots配置，单独指定需要解析的目标包路径，减少不必要的编译开销
• 配置保存后，按Ctrl+Shift+P（macOS为Cmd+Shift+P）调出VSCode命令面板，执行「TypeScript: Restart TS Server」重启TS服务，即可消除报错，拿到完整的智能提示。

备选方案：本地自动生成专属d.ts文件 #

如果开启allowJs后项目编译速度下降明显，可以本地自动生成目标包的d.ts文件长期使用，不需要包维护者支持：

• 在项目中新建临时目录用于生成类型，配置临时TS编译参数：开启allowJs、declaration、emitDeclarationOnly选项，将编译入口指向目标npm包的主入口JS文件
• 执行TS编译命令，编译器会自动遍历包内所有JS文件，根据JSDoc注释生成全量的.d.ts类型声明文件
• 将生成的声明文件移动到项目自建的types/[对应包名]目录下，在tsconfig.json的typeRoots配置中加入本地types目录路径即可正常使用
  注意：当目标npm包升级版本后，需要重新执行一次类型生成流程，避免类型定义和实际代码逻辑不匹配。

不推荐的做法 #

• 仅写一行declare module '包名'的空声明文件：会将整个包标记为any类型，完全丢失JSDoc提供的类型提示，等于放弃类型校验
• 手动逐行编写包的类型定义：效率极低，包版本升级后维护成本极高
• 直接修改node_modules下的包文件添加类型：重新安装依赖后修改会全部丢失，无法在团队成员间同步配置。

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