如何调试通过npm link关联的NPM模块？（VS Code环境）

我之前也碰到过一模一样的问题！npm link确实解决了模块修改不用重复发布的麻烦，但调试起来容易踩坑——加了debugger没反应、断点打不上都是常见问题。下面是我在VS Code里摸出来的靠谱方案，亲测有效：

第一步：确保模块生成Source Map #

这是最容易被忽略的前提！如果你的模块是经过编译的（比如TypeScript、Babel转译），一定要开启source map生成，否则调试器只能定位到编译后的代码，找不到你写的源码。

• TypeScript：在tsconfig.json里设置 "sourceMap": true
• Babel：在babel.config.json或.babelrc里添加 "sourceMaps": "both"
• 打包工具（Rollup/Webpack）：开启source map选项（比如Rollup的output.sourcemap: true）

第二步：配置主项目的VS Code调试（launch.json） #

主项目的调试配置需要明确告诉VS Code：要追踪到链接的本地模块源码，而不是只局限于主项目本身。

打开主项目的.vscode/launch.json，添加或修改如下配置：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Main Project + Linked Module",
      "program": "${workspaceFolder}/src/index.js", // 替换成你的主项目入口文件
      "skipFiles": ["<node_internals>/**"], // 跳过Node内部核心代码，不要跳过node_modules
      "sourceMaps": true,
      "resolveSourceMapLocations": [
        "${workspaceFolder}/**", // 主项目源码
        "../your-local-module/**" // 替换成你的本地模块的相对路径（或绝对路径）
      ]
    }
  ]
}

关键参数说明：

• resolveSourceMapLocations：必须把本地模块的源码路径加进去，这样VS Code才能找到模块的source map，关联到你的源码断点
• skipFiles：只跳过Node内部代码，不要包含node_modules/**，否则会跳过链接的模块代码

第三步：直接调试本地模块本身 #

如果你想单独调试模块的逻辑（比如跑模块的测试用例），可以在模块项目里单独配置launch.json：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Local Module",
      "program": "${workspaceFolder}/test/index.test.js", // 模块的测试入口或示例入口
      "sourceMaps": true,
      "skipFiles": ["<node_internals>/**"]
    }
  ]
}

如果是TypeScript模块，不想每次手动编译，可以用ts-node直接运行：

{
  "type": "node",
  "request": "launch",
  "name": "Debug TS Module",
  "runtimeArgs": ["-r", "ts-node/register"],
  "program": "${workspaceFolder}/src/index.ts",
  "sourceMaps": true,
  "skipFiles": ["<node_internals>/**"]
}

常见坑与解决办法 #

• 断点灰色（未绑定）：检查source map是否生成，以及resolveSourceMapLocations是否包含模块路径；重启VS Code调试会话或刷新窗口（Ctrl+Shift+P → Developer: Reload Window）
• 调试时跳到编译后代码：确认模块的source map路径正确，编译工具没有把source map路径写错
• npm link链接失效：重新在模块项目执行npm link，主项目执行npm link your-module-name，确保node_modules里的模块是软链而非下载的版本

调试流程验证 #

1. 在本地模块的源码里打上断点（或加debugger语句）
2. 启动主项目的调试会话
3. 触发主项目中调用模块的逻辑，调试器会自动跳转到模块的源码断点处

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