VS Code调试自定义NPM库时跳转至TypeScript源文件而非.d.ts文件

我遇到过不少类似的场景，调试器跳转到.d.ts而非TS源码，本质是调试器无法通过source map关联到你的TS源文件，或是默认忽略了node_modules里的库源码映射。咱们一步步来解决：

1. 确保自定义NPM库生成正确的Source Map #

先检查你的库的tsconfig.json，必须配置以下关键选项：

{
  "compilerOptions": {
    "target": "ESNext", // 替换为你需要的目标版本
    "module": "ESNext",
    "outDir": "./dist", // 编译产物输出目录
    "sourceMap": true, // 核心：开启source map生成
    "declaration": true, // 生成.d.ts类型文件
    "declarationMap": false, // 注意：不要开启这个，否则调试器可能优先关联.d.ts的map
    "inlineSources": true, // 可选但推荐：把TS源码嵌入source map，避免路径匹配问题
    "rootDir": "./src" // 指定源码根目录，确保source map路径映射准确
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

• sourceMap: true：必须开启，编译后的.js会生成对应的.js.map文件，记录TS源码与JS代码的映射关系。
• rootDir: "./src"：告诉TS编译器源码的根目录，保证source map里的路径是相对src的，而非混乱的绝对路径。
• inlineSources: true：把TS源码直接嵌入source map，避免根项目因路径差异找不到库的TS文件。

编译完成后，你的dist目录下应该有：

• 编译后的.js文件
• 对应的.js.map文件
• .d.ts类型文件

同时，确保package.json把TS源码、source map都包含在发布包里：

{
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "files": [
    "src",
    "dist"
  ]
}

files字段明确指定要发布的目录，保证src下的TS源码和dist产物都能被打包到NPM包中。

2. 配置根项目的调试器（以VS Code为例） #

在根项目的.vscode/launch.json里，调整调试配置，让调试器识别并加载自定义库的source map：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node", // 前端项目可换成chrome/msedge
      "request": "launch",
      "name": "Debug Root Project",
      "program": "${workspaceFolder}/src/index.ts",
      "sourceMaps": true, // 必须开启source map支持
      "resolveSourceMapLocations": [
        "${workspaceFolder}/**",
        "node_modules/你的自定义库名/**" // 关键：告诉调试器不要忽略这个库的source map
      ],
      "skipFiles": [
        "<node_internals>/**" // 跳过Node内部文件，可选
      ]
    }
  ]
}

• resolveSourceMapLocations：添加你的自定义库路径，默认调试器会忽略node_modules里的source map，所以必须显式包含。

3. 检查构建工具配置（若根项目用Webpack/Vite等） #

如果根项目用了构建工具，要确保它们不丢弃自定义库的source map：

Webpack #

在webpack.config.js中：

module.exports = {
  devtool: 'source-map', // 必须用保留原始source map的选项，比如source-map或inline-source-map
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: 'ts-loader',
        exclude: /node_modules(?!\/你的自定义库名)/ // 不要排除你的自定义库
      }
    ]
  }
};

Vite #

在vite.config.ts中：

import { defineConfig } from 'vite';

export default defineConfig({
  optimizeDeps: {
    exclude: ['你的自定义库名'] // 告诉Vite不要预构建这个库，保留原始source map
  },
  build: {
    sourcemap: true // 开发环境默认开启，生产环境按需开启
  }
});

4. 验证配置是否生效 #

完成以上步骤后：

1. 重新安装自定义库到根项目（本地调试可直接用npm install ../你的库路径）
2. 在根项目调用库函数的代码行添加断点
3. 启动调试，此时应该会跳转到自定义库的TS源文件，而非.d.ts

如果仍有问题，可以打开调试器的开发者工具，查看Sources面板是否能找到你的库的TS源码，或检查.js.map文件里的sources字段是否正确指向TS文件路径。

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