应启用 Chrome 调试端口并配置 launch.json、使用 devtools: true 启动、切换至 puppeteer-core 复用外部 Chrome 实例、在 TypeScript 项目中启用 sourceMap 支持。
如果您在 VSCode 中使用 Puppeteer 进行 浏览器 自动化脚本开发，但无法在断点处暂停执行或变量无法正确显示，则可能是由于调试配置未适配 Puppeteer 的无头模式或进程通信机制。以下是解决此问题的步骤：
本文运行环境：MacBook Pro，macOS Sequoia。
一、启用 Chrome 调试 端口 并配置 launch.json
VSCode 通过 Chrome DevTools Protocol（CDP）连接到 Chromium 实例进行调试，需确保 Puppeteer 启动的浏览器实例暴露调试端口，并被 launch.json 正确引用。
1、在 Puppeteer 启动代码中显式指定 –remote-debugging-port=9222 参数，例如：launch({headless: false, args: ['--remote-debugging-port=9222'] })。
2、在项目根目录创建 .vscode/launch.json，添加类型为 pwa-chrome 的配置项。
3、在配置中设置 url 为 http://localhost:9222，并启用 webRoot 指向源码目录（如 ${workspaceFolder}）。
二、使用 puppeteer.launch({devtools: true}) 启动带开发者 工具 的实例
该方式可绕过端口配置，直接在 Chromium 窗口中启用 DevTools 界面，使 VSCode 能通过自动发现机制建立调试会话。
1、将 Puppeteer 启动参数中的 headless 设为 false，并添加 devtools: true 选项。
2、运行脚本后，Chromium 将弹出独立窗口并附带完整 DevTools 面板。
3、在 VSCode 中启动调试器，选择 Attach to Process 类型配置，VSCode 将自动列出可用的 CDP 目标并连接。
三、切换至 puppeteer-core 并复用已运行的 Chrome 实例
避免 Puppeteer 自行管理浏览器生命周期带来的调试上下文丢失问题，改由外部可控的 Chrome 实例承载调试会话。
1、手动启动 Chrome 并监听调试端口：open -n -a “Google Chrome” –args –remote-debugging-port=9222 –no-first-run（macOS）。
2、在代码中使用 puppeteer-core 替代 puppeteer，调用 puppeteer.connect() 方法连接至 ws://localhost:9222/devtools/browser/… WebSocket 地址。
3、从 Chrome 的 chrome://version/ 页面复制完整的 WebSocket URL，粘贴至 connect() 的 browserWSEndpoint 参数中。
四、在 TypeScript 项目中启用 sourceMap 支持
若调试时断点落在编译后 JS 文件而非原始 TS 文件，说明 sourceMap 未被正确加载或映射路径错误。
1、确认 tsconfig.json 中已启用 sourceMap: true 和 inlineSources: true。
2、检查生成的 .js.map 文件是否与同名 JS 文件位于同一目录，且 map 文件中 sources 字段指向正确的 TS 路径（建议使用相对路径）。
3、在 launch.json 的调试配置中添加 sourceMaps: true 和 outFiles 数组，明确包含 ./dist/**/*.js 等输出路径。
