Next.js使用自定义TypeScript .d.ts时报模块无法解析错误

你配置的typeRoots、include等相关选项，只解决了TypeScript静态类型识别的问题——也就是为什么VS Code能正常读取你写的foo.d.ts，给你提供导入时的类型提示。但.d.ts本质是纯类型描述文件，本身不包含任何可执行的JavaScript逻辑，Next.js底层使用的Webpack在做运行时打包时，根本定位不到foo这个模块对应的真实JS实现，自然就会抛出：

Module not found: Can't resolve 'foo'

这里要明确：纯类型声明文件完全不会参与运行时代码打包，它的唯一作用就是在编译阶段给TS提供类型校验参考，对运行时的模块解析流程没有任何帮助。

第一优先级检查项 #

首先确认你有没有把foo这个库的真实JS代码安装到项目依赖中。不少人写完自定义.d.ts就直接写导入语句，忘了先安装对应的JS库本身：

• 执行安装命令把foo加到项目生产依赖：
  npm install foo / yarn add foo
• 安装完成后，打包器会自动从node_modules目录定位到foo的真实JS入口，配合你写的foo.d.ts做类型匹配，模块找不到的报错就会消失
  注：安装完成后不需要额外调整typeRoots配置，只要你的foo.d.ts中写了declare module 'foo'的模块声明，TypeScript会自动匹配对应模块的类型定义。

第二层级排查项 #

如果你已经安装了foo库但打包依然报错，顺着以下方向检查：

• 简化foo.d.ts的冗余语法：你现在在declare module 'foo'块内部，又重复给接口、命名空间加了declare关键字，这类写法虽然不影响类型识别，但要确保导出的结构和foo库真实的导出结构完全匹配，避免出现类型和实际代码对不上的问题
• 如果你使用的foo是本地自定义的JS模块，没有发布到npm、也没有放到node_modules目录下，光靠.d.ts是没法解决运行时问题的：
  • 可以把模块的真实JS代码放到项目公共目录下，通过相对路径导入，把对应的类型声明放在同路径下
  • 也可以在next.config.js中配置路径别名，把foo的导入路径映射到本地存放的真实JS代码位置，让打包器能定位到实际代码
• 优化tsconfig的include配置：typeRoots的设计初衷是指定全局类类型定义的查找路径，对模块类型的识别帮助有限，不如直接在include配置中显式加入你的类型文件目录，替换为：

  "include": [
    "next-env.d.ts",
    "**/*.ts",
    "**/*.tsx",
    "typings/**/*.d.ts"
  ]
  

• 不要把类型系统的查找逻辑和打包器的模块解析逻辑混为一谈：TS编译器能识别类型声明，不代表底层打包器能找到对应可执行的JS代码，两个流程是完全独立的
• 纯.d.ts文件在TS编译输出时会被完全跳过，不会生成任何可运行的代码，对运行时的模块解析没有任何作用

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