如何在VS Code中调试Mocha+TypeScript+ESM项目

问题 #

配置VS Code调试TypeScript ES模块项目的Mocha测试时，添加experimental-specifier-resolution=node参数后触发ERR_UNKNOWN_FILE_EXTENSION，提示无法加载node_modules/mocha/bin/_mocha（无扩展名文件）。

已用临时方案（不推荐） #

• 移除launch.json中的experimental-specifier-resolution=node参数
• 给所有TypeScript导入手动添加.js扩展名

环境 #

• Node.js v19.3.0
• npm v9.2.0
• 项目包含完整配置文件与测试代码

优雅解决方案 #

方案1：调整Mocha执行入口与调试配置 #

直接调用Mocha带扩展名的核心入口文件，避免加载无扩展名的_mocha文件，同时保留Node的模块解析行为：

1. 更新.vscode/launch.json：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Mocha Tests",
      // 用带扩展名的cli入口替代无扩展名的_mocha
      "program": "${workspaceFolder}/node_modules/mocha/lib/cli/cli.js",
      "args": [
        "--require", "ts-node/register/esm",
        "${workspaceFolder}/test/**/*.spec.ts"
      ],
      "runtimeArgs": [
        "--experimental-specifier-resolution=node",
        "--loader", "ts-node/esm"
      ],
      "console": "integratedTerminal",
      "internalConsoleOptions": "neverOpen"
    }
  ]
}

2. 确保项目配置正确：

• package.json中设置"type": "module"
• tsconfig.json启用ES模块：

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "node",
    "target": "ES2020",
    "esModuleInterop": true,
    "outDir": "./dist"
  },
  "include": ["src/**/*", "test/**/*"]
}

方案2：修复自定义Loader逻辑 #

如果必须使用自定义loader.mjs，需要明确处理Mocha的无扩展名CommonJS文件：

import { readFile } from 'fs/promises';
import { fileURLToPath } from 'url';

export async function load(url, context, defaultLoad) {
  // 拦截mocha的无扩展名文件，按CommonJS格式加载
  if (url.includes('node_modules/mocha/bin/_mocha')) {
    const filePath = fileURLToPath(url);
    const content = await readFile(filePath, 'utf8');
    return { format: 'commonjs', source: content };
  }
  // 其他文件使用默认加载逻辑
  return defaultLoad(url, context, defaultLoad);
}

然后在launch.json的runtimeArgs中添加该loader：

"runtimeArgs": [
  "--experimental-specifier-resolution=node",
  "--loader", "${workspaceFolder}/loader.mjs",
  "--loader", "ts-node/esm"
]

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