ts-node运行时无法识别导入自定义*.d.ts类型声明文件报错求解

问题根因 #

ts-node 默认运行逻辑与 tsc 编译逻辑不一致，默认不会主动加载 tsconfig 中 typeRoots 配置的自定义类型目录下的声明文件，也不会自动识别未被显式包含在编译范围内的 .d.ts 文件，因此会出现 VS Code 和 tsc 编译正常、仅 ts-node 报错的情况。

修复步骤 #

方案1：调整 tsconfig 配置适配 ts-node #

1. 给你的 tsconfig.json 补充 include 字段和 ts-node 专属配置，完整配置如下：

{
  "compilerOptions": {
    "rootDir": "./src",
    "typeRoots": [
      "./src/@types",
      "./node_modules/@types"
    ],
    "outDir": "./dist"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"],
  "extends": "@tsconfig/node16/tsconfig.json",
  "ts-node": {
    "files": true
  }
}

2. 删除代码中显式导入 ../types/discord 的语句。你是在做 discord.js 类型扩展，只要声明文件符合如下格式，且放在 src/@types 目录下，不需要手动导入即可被全局识别：

import { Client, Collection } from 'discord.js';

declare module 'discord.js' {
  interface Client {
    // 替换为你实际的 commands 类型
    commands: Collection<string, YourCommandType>;
  }
}

3. 重新执行 npm run dev 验证即可。

方案2：修改 ts-node 启动参数 #

如果不想改 tsconfig，直接把启动命令中的 ts-node ./src/index.ts 改为 ts-node --files ./src/index.ts，同步调整 nodemon 配置里的启动指令即可。

主流替代工具推荐 #

如果不想折腾 ts-node 的配置问题，可以用更省心的开发工具：

• tsx：基于 esbuild 开发的 TypeScript 运行时，零配置、启动速度快，对 ESM 和 CommonJS 兼容性好，直接替换启动指令为 tsx ./src/index.ts 即可，自带监听模式可替代 nodemon：tsx watch ./src/index.ts
• @swc-node/register：基于 SWC 编译，性能远高于 ts-node，配置逻辑和 ts-node 接近但几乎没有类型解析的兼容性问题。

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