Webpack使用ts-loader时.d.ts文件不存在/非模块报错如何正确配置

问题根源 #

.d.ts是TypeScript专用的类型声明文件，仅用于编译阶段的类型校验，本身不包含运行时代码，不需要被Webpack打包进最终产物，因此绝对不能将.d.ts加入resolve.extensions数组，否则Webpack会尝试把它当做可执行模块加载，自然会抛出「不是有效模块」的报错。
你最初遇到的「找不到index文件」报错，本质是Webpack在处理你对类型的导入语句时，尝试寻找对应路径的运行时源码文件，没有找到导致的。

解决方案 #

1. 恢复Webpack的resolve.extensions默认配置 #

移除之前加入的.d.ts后缀，仅保留可执行代码的后缀即可：

// webpack.config.js
module.exports = {
  resolve: {
    // 按项目实际技术栈调整即可，不需要加.d.ts
    extensions: ['.ts', '.tsx', '.js', '.jsx', '.json']
  }
}

2. 确保类型声明被TS识别 #

在tsconfig.json的include配置中，加入你抽离的index.d.ts所在路径，保证TS编译阶段能读取到对应的类型定义：

// tsconfig.json
{
  "include": [
    "src/**/*",
    "src/index.d.ts" // 按你的实际文件路径修改
  ]
}

3. 所有对纯类型的导入都使用类型导入语法 #

TS 3.8及以上版本支持import type语法，明确标记导入的内容仅为类型，这类导入会在TS编译阶段被完全擦除，Webpack打包时根本不会处理对应的导入路径，也就不会出现找不到文件的报错：

// 错误写法：Webpack会尝试寻找该路径对应的运行时文件
import { SomeCustomType } from './your-type-dir'

// 正确写法：仅类型导入，编译后自动擦除，Webpack不会处理
import type { SomeCustomType } from './your-type-dir'

4. 校验ts-loader配置 #

确认ts-loader配置没有通过exclude过滤掉你的.d.ts文件，如果开启了transpileOnly配置，需要搭配fork-ts-checker-webpack-plugin做独立的类型校验，避免类型声明不生效。

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