VSCode如何自动附加调试进程_Auto Attach功能使用指南

autoAttach 是 vscode 监听本地 9229 端口（默认）上由 node –inspect 启动的 Node.js 进程的调试功能，仅对显式开启 CDP 调试端口的进程生效，不支持已运行或未启用调试的进程。

VSCode 的 autoAttach 功能不是“点一下就自动连上任意进程”的万能开关，它只对满足特定启动条件的 Node.js 进程生效——核心是进程必须由 VSCode 启动（或通过 node --inspect 显式开启调试端口），且 VSCode 需处于监听状态。

什么是 autoAttach？它监听什么进程

autoAttach 是 VSCode 调试器在后台持续监听本地 127.0.0.1:9229（或其他指定端口）上新出现的 chrome DevTools Protocol（CDP）调试服务。它不扫描系统所有进程，也不支持 attach 到已运行的、未开启 --inspect 的 Node 进程。

• 仅响应带 --inspect、--inspect-brk 或 --inspect-port=xxx 启动的 Node 进程
• 进程启动时若端口被占用，会自动尝试下一个可用端口（如 9230、9231），autoAttach 默认只监听 9229；如需扩展，需配置 port 或 ports
• 不支持 attach 到 electron 主进程（除非手动加 --inspect=xxx）、python、go 等其他语言进程

启用 autoAttach 的两种方式（推荐 launch.json 方式）

全局设置易误触发，建议优先在项目级 .vscode/launch.json 中配置。VSCode 会优先读取当前工作区的配置。

{   "version": "0.2.0",   "configurations": [],   "autoAttach": {     "transport": "inspector",     "supported": true,     "enable": true,     "Filter": "smart"   } }

• transport: "inspector" 表示监听 CDP 协议（node.js 8+ 默认）；不要设为 "legacy"（已废弃）
• filter: "smart" 仅 attach 到当前工作区路径下启动的 Node 进程；设为 "all" 会 attach 所有匹配进程（含 npm script、全局 CLI 工具等，易干扰）
• 无需额外配置 port：默认监听 9229；若需监听多个端口（如 9229–9235），可改用 "ports": [9229, 9230, 9231, 9232, 9233, 9234, 9235]

常见失败场景和排查步骤

看到“Auto attach failed: Could not find debug adapter”或进程没被自动 attach，大概率是启动方式或配置不匹配。

• 检查 Node 进程是否真开启了调试：运行 ps aux | grep inspect（macos/linux）或 Get-Process | select-String inspect（PowerShell），确认命令行含 --inspect
• 确认 VSCode 已加载该工作区，且 launch.json 存在于 .vscode/ 目录下（不是用户级 settings.json）
• 关闭其他调试器或 ide（如 webstorm、chrome devtools），它们可能占用了 9229 端口
• 终端中手动启动时加 --inspect-brk：例如 node --inspect-brk index.js，这样进程会在第一行暂停，给 VSCode 更多时间捕获
• windows 用户注意：PowerShell 默认禁用脚本执行策略，若用 npm run dev 启动，确保 script 中明确写了 --inspect，而不是依赖 cross-env 但未透传

与 launch 配置共存时的行为逻辑

当 launch.json 中既有常规 launch 配置，又启用了 autoAttach，两者互不干扰，但有优先级：

• 按 F5 启动的是 launch 配置（如 node: Launch Program），此时 autoAttach 不介入
• 在终端里另起一个 node --inspect app.js，才会触发 autoAttach
• 如果同时存在多个 autoAttach 配置（如多个工作区打开），只有最顶层活动工作区的配置生效
• 禁用某工作区的 autoAttach：删掉 launch.json 中的 autoAttach 块，或设 "enable": false

真正关键的一点是：autoAttach 不是“魔法”，它依赖 Node 进程主动暴露调试端口。很多框架（如 Next.js、Nuxt）的 dev server 默认不开 --inspect，得手动加参数或改 package.json script —— 比如把 "dev": "next dev" 改成 "dev": "next dev --inspect"，否则 VSCode 根本收不到信号。