atom调试按钮灰显的根本原因是dap后端缺失或配置错误：未全局安装node-debug2/debugpy、路径未正确配置、.debugger.json文件名/位置/字段错误，或未重启atom导致dap客户端未注册。
Atom 本身不跑调试逻辑，所谓“代码跟踪调试”实际是靠外部调试适配器（DAP 后端）+ 插件 UI 协同完成的。没装对适配器、路径配错、配置文件放错位置，按钮就永远灰着——这不是 Atom 的问题，是整个 DAP 链路断在了底层。
node-debug2 装了但 Start Debugging 按钮还是灰的
常见错误现象：Could not find debug adapter 或控制台报 spawn ENOENT；本质是 Atom 找不到 node-debug2 可执行文件。
- 必须全局安装：
npm install -g node-debug2（本地安装不生效，Atom 不会去node_modules/.bin里找） - 检查是否真能执行：
node-debug2 --version，如果报 command not found，说明 PATH 没生效或安装失败 - atom-ide-debugger 插件需手动指定路径：设置项中填
node-debug2的绝对路径（如/usr/local/bin/node-debug2），不能留空 - 重启 Atom —— 插件启用后不重启，DAP 客户端根本不会注册
Python 调试用 debugpy 还是 ptvsd
ptvsd 已于 2020 年正式弃用，debugpy 是当前唯一被 dbg-python 插件支持的后端。混用会导致连接失败或断点不命中。
- 装 debugpy：
pip install debugpy（推荐用户级安装，避免权限问题） - 验证监听能力：
python -m debugpy --status-port 5678 --log-to-stderr，看到Debugpy server started才算通 - dbg-python 插件不读
.debugger.json，它只认项目根目录下有pyproject.toml或setup.py才激活 UI - 断点打在 .py 文件里才有效；.ipynb 或编译后 .pyc 不支持
.debugger.json 配置写错的典型表现
这个文件只被 dbg-* 系列插件读取（如 dbg-python），atom-ide-debugger 完全无视它。名字、路径、字段大小写错一个，整个配置就静默失效。
- 必须放在项目**根目录**，文件名严格为
.debugger.json（开头的点不能漏） -
"type": "python"大小写敏感，写成"Type"或"PYTHON"都跳过 -
"module": "myapp.main"是模块导入路径，不是文件路径；"./main.py"会直接报错 - Node.js attach 模式要填
"processId"，但 Atom 不提供选择界面，得先ps aux | grep node手动查 PID
为什么断点打了但程序不暂停
不是代码没走到，而是调试器根本没接管进程。最常被忽略的是：调试器启动后是否真的连上了目标进程？
- Python 场景下，运行命令必须带 debugpy 参数：
python -m debugpy --listen 127.0.0.1:5678 myapp/main.py - Node.js 场景下，不能直接
node index.js，得加--inspect：node --inspect=9229 index.js - Atom 插件只是客户端，它不负责启动被调进程——你得自己起服务，再让 Atom attach 上去
- 检查端口占用：
lsof -i :5678（macOS/Linux）或netstat -ano | findstr :5678（Windows）
真正卡住人的从来不是界面上那个“开始调试”按钮，而是 debugpy 进程有没有监听成功、node-debug2 有没有被正确 spawn、以及你的项目结构是否满足插件的自动激活条件——这些都得翻开发者工具 Console 和终端日志才能定位。
