VSCode调试TypeScript Node.js项目：import与文件扩展名循环报错

问题根源分析 #

你遇到的两个错误本质是Node.js对ES模块的处理规则与VSCode调试配置不匹配导致的：

• SyntaxError: Cannot use import statement outside a module：Node默认将文件视为CommonJS模块，ES模块的import语法需要在package.json中声明"type": "module"。
• ERR_UNKNOWN_FILE_EXTENSION: ".ts"：Node本身不识别.ts扩展名，添加"type": "module"后直接调试.ts文件会触发该错误；而终端运行正常是因为你执行的是编译后的.js文件。

以下提供两种可靠的解决方案，按需选择：

方案1：调试编译后的JS文件（推荐，与终端运行逻辑一致） #

该方案复用你已有的编译流程，通过Source Map映射断点到TS源文件，稳定性最高。

1. 确保tsconfig.json配置正确 #

必须开启sourceMap，否则VSCode无法将JS断点映射到TS文件：

{
  "compilerOptions": {
    "target": "ES2020", // 匹配你的Node.js 19.2.0版本
    "module": "ESNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "sourceMap": true // 关键配置，生成Source Map文件
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

2. 配置launch.json #

修改.vscode/launch.json，指定调试编译后的JS入口，并开启Source Map支持：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Compiled JS",
      "program": "${workspaceFolder}/dist/main.js", // 指向编译后的入口文件
      "sourceMaps": true,
      "outFiles": ["${workspaceFolder}/dist/**/*.js"], // 指定JS文件目录
      "runtimeArgs": ["--experimental-specifier-resolution=node"] // 可选，解决ES模块导入路径无扩展名的问题
    }
  ]
}

3. 自动编译（可选） #

如果不想每次调试前手动执行tsc，可以添加预编译任务：

• 创建.vscode/tasks.json：

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "tsc",
      "type": "shell",
      "command": "tsc",
      "problemMatcher": "$tsc",
      "group": {
        "kind": "build",
        "isDefault": true
      }
    }
  ]
}

• 在launch.json的配置中添加"preLaunchTask": "tsc"，调试前会自动执行编译。

方案2：直接调试TS文件（无需预编译） #

该方案使用ts-node-esm直接转译TS文件并调试，适合快速开发场景。

1. 安装依赖 #

本地安装ts-node和typescript（避免全局版本冲突）：

npm install --save-dev ts-node typescript

2. 配置launch.json #

修改.vscode/launch.json，使用ts-node-esm作为运行时：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug TS Directly",
      "program": "${workspaceFolder}/src/main.ts", // 直接指向TS入口文件
      "runtimeExecutable": "npx",
      "runtimeArgs": [
        "ts-node-esm",
        "--experimental-specifier-resolution=node"
      ],
      "sourceMaps": true,
      "skipFiles": ["<node_internals>/**"] // 跳过Node内部文件，优化调试体验
    }
  ]
}

额外注意事项 #

• 确保所有ES模块导入路径带扩展名（如import { func } from './utils.js'），或通过--experimental-specifier-resolution=node允许省略扩展名。
• 更新VSCode的「JavaScript Debugger」扩展到最新版本，避免兼容性问题。
• 调试前关闭终端中可能运行的tsc --watch进程，避免文件冲突。

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