Module not found报错：无法解析相对路径.d.ts文件问题咨询

报错信息 #

Module not found: Error: Can't resolve the relative path .d.ts file
触发场景：导入带export declare语法的.d.ts文件时抛出异常，尝试直接引用目标.d.ts文件（实际业务逻辑无需显式引用该文件）、修改导入路径均无法解决；该.d.ts文件内容迁移自原本通过@project_name/core别名导入的路径，除上述模块找不到报错外无其他编译异常。

排查解决步骤 #

• 移除所有.d.ts文件的显式导入语句
  .d.ts是TypeScript专属的类型声明文件，仅在编译阶段做类型校验，不会被输出为可运行的JS代码，禁止在业务代码中写import X from './path/xxx.d.ts'形式的显式引用。这类显式导入会让webpack/Vite等打包工具把.d.ts当做运行时模块查找实体文件，直接触发模块找不到报错，TS本身会自动扫描识别配置范围内的.d.ts文件，不需要手动导入。
• 校验tsconfig.json的类型扫描规则
  打开项目根目录的tsconfig.json，重点核对三个配置项：
  • include：必须覆盖迁移后.d.ts文件的存放路径，比如文件放在src/types/目录下，需要保证配置包含"src/**/*.d.ts"规则，让TS能扫描到该文件
  • exclude：检查是否误将.d.ts所在目录加入了排除列表，如有则移除
  • 全局搜索代码中残留的从@project_name/core导入对应类型的语句，全部清理干净，避免旧导入路径触发的解析错误
• 修正打包工具的后缀解析配置
  检查打包工具的扩展名解析列表，不要把.d.ts加入可解析的运行时文件后缀：
  • webpack用户查看resolve.extensions配置，如果存在.d.ts项直接删除，webpack默认不需要解析类型声明文件，类型处理交给TS编译链路即可
  • Vite用户查看resolve.extensions配置，同理移除.d.ts项，避免Vite优先匹配.d.ts文件作为运行时模块加载
• 调整.d.ts文件的导出写法
  如果迁移的是全局通用类型，直接删除文件顶部的export/export declare关键字，写成全局声明即可，不需要导入就能在全项目使用；如果是模块级别的类型声明，不要用相对路径硬引用，可以将声明文件所在目录加入tsconfig的typeRoots配置列表，让TS自动识别。
• 清理缓存后重试
  上述配置修改完成后，删除项目下的node_modules/.cache缓存目录，编辑器内重启TS服务（VSCode可通过命令面板执行TypeScript: Restart TS Server），重新执行编译命令即可，避免旧缓存残留导致的误报。

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