VSCode断点无法绑定npm link的TypeScript私有包问题排查

1. 调整私有npm包的tsconfig.json #

在包的compilerOptions中添加sourcemap相关配置，确保编译时生成能关联源文件的映射：

{
  "compilerOptions": {
    "esModuleInterop": true,
    "module": "commonjs",
    "target": "es2015",
    "declaration": true,
    "outDir": "./dist",
    "experimentalDecorators": true,
    "moduleResolution": "node",
    // 新增sourcemap配置
    "sourceMap": true,
    "inlineSources": true,
    "declarationMap": true
  },
  "include": [
    "src/**/*.ts"
  ]
}

• sourceMap: 生成.js.map文件，建立编译后JS与源TS的关联
• inlineSources: 将源TS代码嵌入sourcemap，确保调试器可直接访问源码
• declarationMap: 生成.d.ts.map，让类型定义也关联到源文件

修改后重启tsc --watch，确认dist目录下生成对应的.map文件。

2. 配置Next.js应用识别link包的sourcemap #

Next.js默认忽略node_modules内包的sourcemap，而npm link的包会被归入该目录，需修改next.config.js：

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  // 指定需要转译的私有包（替换为实际包名，多个包用数组）
  transpilePackages: ['your-private-package'],
  webpack: (config, { dev, isServer }) => {
    if (dev) {
      // 开发环境启用sourcemap支持
      config.devtool = 'source-map';
      // 加载并处理私有包的sourcemap
      config.module.rules.push({
        test: /\.js$/,
        enforce: 'pre',
        use: ['source-map-loader'],
        include: /node_modules\/your-private-package/, // 替换为实际包名
      });
    }
    return config;
  },
};

module.exports = nextConfig;

先安装依赖：

npm install source-map-loader --save-dev

3. 调整VSCode调试配置（launch.json） #

在.vscode/launch.json中明确允许解析私有包的sourcemap：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug full stack",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev",
      "serverReadyAction": {
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "action": "debugWithChrome"
      },
      "sourceMaps": true,
      "resolveSourceMapLocations": [
        "${workspaceFolder}/**",
        "!**/node_modules/**",
        "**/node_modules/your-private-package/**" // 允许调试目标私有包的sourcemap
      ]
    }
  ]
}

4. 清理缓存并重启服务 #

• 停止Next.js开发服务器和私有包的tsc --watch
• 删除Next.js的.next目录和私有包的dist目录
• 重新启动私有包的tsc --watch，再启动Next.js的npm run dev
• 重新设置断点，即可绑定到私有包的源TS文件

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