VSCode调试带src目录的Next.js+TypeScript项目时断点未绑定问题

问题背景 #

项目根目录包含front和back文件夹，Next.js项目位于front下，源码存放在front/src，编译产物输出到front/dist。使用Yarn+TypeScript开发，调试时断点始终显示“Unbound breakpoint”，尝试官方配置及多种修改方案均无效。

当前配置文件 #

front/tsconfig.json #

{
  "compilerOptions": {
    "allowJs": true,
    "alwaysStrict": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "lib": ["dom", "es2017"],
    "module": "esnext",
    "moduleResolution": "node",
    "noEmit": true,
    "noFallthroughCasesInSwitch": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "resolveJsonModule": true,
    "skipLibCheck": true,
    "strict": true,
    "target": "esnext",
    "sourceMap": true
  },
  "exclude": ["node_modules"],
  "include": ["**/*.ts", "**/*.tsx"]
}

.vscode/launch.json #

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug server-side",
      "type": "node-terminal",
      "request": "launch",
      "cwd": "${workspaceFolder}/front",
      "preLaunchTask": "tsc: build - front/tsconfig.json",
      "sourceMaps": true,
      "sourceMapPathOverrides": {
        "webpack:///./src/*": "${workspaceFolder}/front/dist/*",
        "webpack:///src/*": "${workspaceFolder}/front/dist/*"
      },
      "command": "npm run dev"
      // "command": "yarn dev"
      // "command": "${workspaceFolder}/front/node_modules/next/dist/bin/next ./src"
    },
    {
      "name": "Next.js: debug client-side",
      "type": "chrome",
      "request": "launch",
      "cwd": "${workspaceFolder}/front",
      "url": "http://localhost:3000"
    },
    {
      "name": "Next.js: debug full stack",
      "type": "node-terminal",
      "cwd": "${workspaceFolder}/front",
      "request": "launch",
      "sourceMaps": true,
      "sourceMapPathOverrides": {
        "webpack:///./src/*": "${workspaceFolder}/front/dist/*",
        "webpack:///src/*": "${workspaceFolder}/front/dist/*"
      },
      "preLaunchTask": "tsc: build - front/tsconfig.json",
      "command": "npm run dev",
      // "command": "yarn dev",
      // "command": "${workspaceFolder}/front/node_modules/next/dist/bin/next ./src",
      "serverReadyAction": {
        "pattern": "started server on .+, url: (https?://.+)\",
        "uriFormat": "%s",
        "action": "debugWithChrome"
      }
    }
  ]
}

.vscode/tasks.json #

{
  "version": "2.0.0",
  "tasks": [
    {
      "type": "typescript",
      "tsconfig": "front/tsconfig.json",
      "problemMatcher": ["$tsc"],
      "group": "build",
      "label": "tsc: build - front/tsconfig.json"
    }
  ]
}

解决步骤 #

1. 修正tsconfig.json核心配置 #

当前noEmit: true会阻止TypeScript生成编译文件和source map，这是断点无法绑定的关键原因，同时需明确指定输出目录：

{
  "compilerOptions": {
    // 保留原有其他配置
    "noEmit": false,  // 改为false，允许生成文件
    "outDir": "./dist",  // 指定编译产物输出目录
    "sourceMap": true
  },
  // 其他配置不变
}

2. 调整launch.json映射规则与任务设置 #

Next.js调试需要关联原始源码文件而非编译后的dist文件，同时移除不必要的前置编译任务（Next.js dev模式会自行处理TS编译）：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug server-side",
      "type": "node-terminal",
      "request": "launch",
      "cwd": "${workspaceFolder}/front",
      "sourceMaps": true,
      "sourceMapPathOverrides": {
        "webpack://_N_E/*": "${workspaceFolder}/front/src/*",
        "webpack:///./src/*": "${workspaceFolder}/front/src/*",
        "webpack:///src/*": "${workspaceFolder}/front/src/*"
      },
      "command": "yarn dev",  // 改用Yarn命令匹配项目依赖管理方式
      "runtimeArgs": ["--inspect"]  // 开启Node检查模式，适配Next.js 13+
    },
    {
      "name": "Next.js: debug client-side",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000",
      "sourceMaps": true,
      "webRoot": "${workspaceFolder}/front/src",
      "sourceMapPathOverrides": {
        "webpack://_N_E/*": "${webRoot}/*"
      }
    },
    {
      "name": "Next.js: debug full stack",
      "type": "node-terminal",
      "cwd": "${workspaceFolder}/front",
      "request": "launch",
      "sourceMaps": true,
      "sourceMapPathOverrides": {
        "webpack://_N_E/*": "${workspaceFolder}/front/src/*",
        "webpack:///./src/*": "${workspaceFolder}/front/src/*",
        "webpack:///src/*": "${workspaceFolder}/front/src/*"
      },
      "command": "yarn dev",
      "runtimeArgs": ["--inspect"],
      "serverReadyAction": {
        "pattern": "started server on .+, url: (https?://.+)",
        "uriFormat": "%s",
        "action": "debugWithChrome"
      }
    }
  ]
}

3. 基础环境检查 #

• 更新VSCode的JavaScript/TypeScript插件到最新版本
• 关闭VSCode的自动附加功能（设置中搜索debug.javascript.autoAttachFilter，设为none）
• 清理front/dist目录，重启VSCode后再尝试调试

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