VSCode Docker远程调试Node.js单步误入node_modules解决方法

问题复现路径 #

• 断点可被调试器正常识别，命中后可正常暂停
• 按下F11（Step Into）进入自有业务函数时，调试器会直接打开/node_modules/async-listener/es6-wrapped-promise.js，误入第三方依赖代码
• 已配置skipFiles规则期望忽略node_modules下文件，但规则未生效；按下Shift+F11（Step Out）返回时会直接跳到目标函数末尾，无法逐行调试函数内部逻辑

现有配置参考 #

launch.json 初始配置 #

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "My API debugg Config",
            "type": "node",
            "request": "attach",
            "restart": true,
            "port": 9229,
            "address": "localhost",
            "localRoot": "${workspaceFolder}/my-api/src/",
            "remoteRoot": "/home/app/src/",
            "protocol": "inspector",
            "skipFiles": [
                "/home/app/node_modules/**/*.js",
                "${workspaceFolder}/my-api/node_modules/**/*.js",
                "<node_internals>/**/*.js"
            ]
        }
    ]
}

已尝试追加的无效配置 #

{
"skipFiles": [
    "/home/app/node_modules/**/*.js",
    "${workspaceFolder}/my-api/node_modules/**/*.js",
    "/home/app/node_modules/async-listener/es6-wrapped-promise.js",
    "<node_internals>/**/*.js"
],
"smartStep": true,
"sourceMaps": true
}

Docker环境启动命令（package.json dev脚本） #

"dev": "nodemon --inspect=0.0.0.0:9229 --legacy-watch -P 4000 --exec node -r ts-node/register src/index.ts",

相关依赖版本 #

{
    "ts-node": "^9.1.1",
    "tslint": "^6.1.3",
    "typescript": "^4.1.5"
}

tsconfig.json配置 #

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "es2016",
    "outDir": "dist",
    "moduleResolution": "node",
    "skipLibCheck": true,
    "emitDecoratorMetadata": true,
    "declaration": true,
    "experimentalDecorators": true,
    "noImplicitAny": false,
    "inlineSources": true,
    "sourceMap": true
  },
  "include": [
    "src"
  ],
  "exclude": []
}

修复步骤 #

1. 修正路径映射配置
   原有localRoot和remoteRoot只配置到src目录，和src同级的node_modules目录不在路径映射范围内，导致写死的node_modules绝对路径规则无法匹配到容器内实际运行的文件。将两个配置项修改为指向项目根目录：

   "localRoot": "${workspaceFolder}/my-api/",
   "remoteRoot": "/home/app/",
   

2. 简化skipFiles匹配规则
   去掉写死的本地、远程绝对路径，改用通用通配符适配所有路径场景，同时补充对async-hook类注入代码的匹配：

   "skipFiles": [
       "<node_internals>/**/*.js",
       "**/node_modules/**/*.js",
       "**/async-listener/**/*.js"
   ]
   

   规则中开头的**可匹配任意层级的父目录，不管是容器内远程路径还是本地工作区路径，都能正确命中需要跳过的第三方文件。
3. 优化ts-node启动参数
   原有启动命令未指定忽略node_modules目录规则，会导致ts-node编译处理第三方依赖时生成的sourcemap路径错乱。将dev脚本修改为：

   "dev": "nodemon --inspect=0.0.0.0:9229 --legacy-watch -P 4000 --ignore 'node_modules/**' --exec node -r ts-node/register/transpile-only src/index.ts",
   

   新增的--ignore 'node_modules/**'参数强制nodemon忽略node_modules下的文件变更，ts-node/register/transpile-only模式跳过类型检查，减少运行时注入的额外代码路径。
4. 手动补充跳过规则（可选兜底）
   重启调试会话后如果仍偶然进入async-listener文件，直接在打开的文件编辑器空白处右键，选择跳过此文件，VSCode会自动将该文件路径追加到skipFiles规则中，后续调试不会再进入该文件。

配置完成后重启Docker容器内的Node服务，重新附加调试器即可正常逐行调试自有业务代码，F11单步进入时不会再误入node_modules下的第三方依赖。

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