nvim debug dap

Neovim DAP 调试

这套配置使用 nvim-dap 负责调试协议，nvim-dap-view 提供底部调试面板，JavaScript 调试器使用 Microsoft vscode-js-debug

快速开始

1. 将光标放在希望暂停的代码行，按 <leader>db 设置断点
2. 按 <leader>dc，从列表中选择调试配置
3. 程序命中断点后，在底部面板检查变量、调用栈和线程
4. 使用单步快捷键执行代码，结束后按 <leader>dt 关闭全部调试 session 与面板

已有调试 session 时，<leader>dc 会直接继续运行，不再重复显示配置选择器

全局快捷键

快捷键	功能
<leader>db	切换当前行断点
<leader>dc	启动调试或继续到下一个断点
<leader>dp	暂停程序
<leader>di	进入当前函数
<leader>do	执行当前行，不进入函数
<leader>dO	跳出当前函数
<leader>dr	重启当前调试 session
<leader>dl	重新运行上一次配置
<leader>dt	终止全部调试 session，并关闭调试面板
<leader>dd	断开当前调试器连接
<leader>du	打开或关闭底部调试面板
<leader>dv	切换代码行末尾的变量值
<leader>de	查看或计算光标下的表达式，Normal 和 Visual 模式均可用

调试面板

<leader>du 打开的面板包含以下区域：

区域	快捷键	内容
Watches	W	自定义监视表达式
Scopes	S	当前栈帧中的局部变量和作用域
Exceptions	E	异常断点过滤器
Breakpoints	B	当前项目的全部断点
Threads	T	session、线程与调用栈
REPL	R	调试器交互控制台

面板顶部按钮依次提供继续、单步、重启、终止等操作；键盘操作优先使用 <leader>d* 快捷键

Breakpoints 列表

Breakpoints 区域做了额外交互增强：

快捷键	功能
j / k	移动选择，并在源码窗口实时预览断点位置
Enter	确认预览并正式跳转到该断点
d	删除光标所在的断点
Ctrl-w Enter	选择窗口跳转方式
q	关闭整个调试面板

实时预览不会立即改变原编辑位置。如果没有按 Enter 确认，而是按 q、Ctrl-w 或通过其他方式离开面板，源码窗口会恢复原来的 buffer、光标和视图

过长的断点路径会折叠中间层级，例如：

frontend/electron/renderer/views/cards/[id]/components/CardSummary/index.tsx
→ frontend/…/components/CardSummary/index.tsx

JavaScript 与 TypeScript

JavaScript、TypeScript、JSX 和 TSX 共用同一组配置，不会根据扩展名猜测代码属于 Node、Electron Main 或 Renderer

配置	用途
Launch current file	使用 Node.js 运行当前文件
Attach to process	从进程列表选择并附加 Node.js 进程
Launch current file with Bun	使用 bun run 调试当前文件
Debug package.json script	选择并调试最近 package.json 中的 script
Launch browser	启动浏览器并调试前端页面
Launch Electron main process	只启动 Electron Main 调试
Launch Electron and attach renderer	同时调试 Electron Main 与 Renderer
Attach Electron renderer process	附加到已经启动的 Electron Renderer

调试器默认跳过 Node 内置模块、node_modules 和 Vite 注入的 @react-refresh 虚拟源码，避免单步执行进入依赖内部

调试 package.json scripts

选择 Debug package.json script 后，配置会从当前文件向上寻找最近的 package.json，列出其中可执行的 scripts，并根据以下顺序选择包管理器：

1. package.json 的 packageManager 字段
2. pnpm-lock.yaml
3. bun.lock 或 bun.lockb
4. yarn.lock
5. package-lock.json 或 npm-shrinkwrap.json
6. 找不到时回退到 npm

开发服务器输出 URL 后，调试器会自动启动浏览器 session，并使用项目目录作为 webRoot。配置会关闭终端颜色输出，避免 ANSI 控制字符污染调试终端

调试浏览器

Launch browser 会提示输入 URL。默认值按以下规则生成：

1. 使用该项目上次输入并保存的 URL
2. 检查最近的 Vite 配置中的 server.port
3. 检查 .env* 中的 PORT、VITE_PORT 等端口变量
4. 回退到 http://localhost:5173

URL 按项目保存在 Neovim state 目录的 dap/browser-urls.json 中

Electron

Electron 自动配置只识别使用 electron-vite 的项目。项目根目录从当前文件和工作目录向上查找，不依赖固定的 frontend/electron 目录结构

推荐选择 Launch Electron and attach renderer：

1. 使用 electron-vite --sourcemap 启动 Main 进程
2. 开放 Renderer DevTools 端口 9222
3. 等待 Renderer 端口就绪
4. 创建独立的 Renderer session
5. Main 或 Renderer 任意一侧命中断点时，面板自动切换到对应 session

Main 和 Renderer 可以同时调试，并非互斥。Renderer 的 webRoot 优先使用当前文件向上最近的 index.html 所在目录，以便 sourcemap 正确映射 TS、TSX 和 JS 源码

如果 Main 停在早期断点，Renderer 尚未创建，配置会等待 Main 继续运行后再附加 Renderer；等待超过 60 秒才会提示超时

Python、Go 与 Rust

语言	配置与依赖
Python	使用 Neovim data 目录中的专用 debugpy Python 环境
Go	使用 nvim-dap-go 与 dlv，调试当前文件所在 package
Rust	使用 lldb-dap；可编译并调试当前单文件，或选择 target/debug 中的可执行文件

macOS 调试 Go 需要启用 Developer Tools 权限：

sudo /usr/sbin/DevToolsSecurity -enable

断点持久化

断点由 auto-session 随项目 session 保存和恢复，包括普通断点、条件、命中条件和 log message。断点标记不依赖打开 DAP 面板，恢复 session 后会直接显示在 status column 中

常见问题

断点没有变成已验证状态

通常表示调试器尚未加载对应源码，或 sourcemap 无法将运行产物映射回源文件。前端项目优先检查构建工具是否启用 sourcemap，以及 webRoot 是否指向实际页面根目录

出现 dap-src:// 虚拟文件

这通常是运行时或构建工具注入的虚拟源码。配置已经跳过 Node 内置模块、依赖目录和 @react-refresh；如果仍进入其他虚拟模块，需要根据稳定的 source path 补充 skipFiles

面板显示 No active session

这只表示当前没有正在运行的调试 session。可以按 q 关闭面板，或按 <leader>dc 启动新的调试配置

退出 Neovim 前如何确保子进程结束

先按 <leader>dt。该操作会递归终止全部调试 session，并关闭调试面板