使用tsx的Express项目VSCode断点无法设置问题排查

以下是常见问题点和对应解决方法：

一、核心配置检查 #

1. tsconfig.json 必须开启源映射 #

断点调试依赖源映射文件（.map），确保你的tsconfig.json包含关键配置：

{
  "compilerOptions": {
    "sourceMap": true, // 核心配置，必须开启
    "rootDir": "./src", // 指定源码根目录
    "outDir": "./dist", // 可选但建议配置，指定编译输出目录
    "target": "ES2020",
    "module": "CommonJS",
    "esModuleInterop": true
  },
  "include": ["src/**/*"]
}

2. .vscode/launch.json 配置需匹配TSX运行逻辑 #

如果项目入口是src/index.ts，正确的launch.json配置如下：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug TSX Express",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/src/index.ts", // 对应你的实际入口文件路径
      "runtimeArgs": ["--loader", "tsx"], // 告诉Node使用tsx加载器处理TS文件
      "sourceMaps": true,
      "skipFiles": ["<node_internals>/**"], // 跳过Node内部文件，避免调试时进入无关代码
      "console": "integratedTerminal", // 使用VSCode集成终端输出日志
      "env": { "NODE_ENV": "development" } // 可选，设置开发环境变量
    }
  ]
}

注意：如果入口是server.ts或app.ts，需同步修改program的路径。

3. package.json 启动脚本避免干扰参数 #

日常开发的dev脚本可以用tsx watch，但调试时不要依赖该脚本，直接用VSCode调试配置启动：

{
  "scripts": {
    "start": "tsx src/index.ts",
    "dev": "tsx watch src/index.ts"
  },
  "dependencies": {
    "express": "^4.18.2"
  },
  "devDependencies": {
    "@types/express": "^4.17.21",
    "@types/node": "^20.10.4",
    "tsx": "^4.7.0",
    "typescript": "^5.3.3"
  }
}

二、常见排查步骤 #

• 确认VSCode安装了最新的TypeScript插件，旧版本可能存在兼容性问题
• 清理项目根目录下的.map文件和dist目录，重启调试
• 断点不要打在空行、注释或异步回调的外层（比如要打在app.get()回调函数内部的代码行）
• 如果断点显示为灰色（未绑定），检查launch.json的program路径是否正确，以及tsconfig的include是否包含断点所在文件

三、调试启动流程 #

1. 打开VSCode左侧「运行和调试」面板（快捷键Ctrl+Shift+D）
2. 顶部下拉菜单选择配置好的Debug TSX Express
3. 点击绿色启动按钮，进程启动后触发断点会自动暂停

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