Atom断点调试非开箱即用，依赖DAP后端（如debugpy、node-debug2）与UI插件协同；按钮灰显主因是DAP链路断裂，包括未全局安装适配器、路径配置错误、未在项目根目录打开、插件冲突或未重启Atom。
Atom 的断点调试不是开箱即用的功能，它依赖外部调试适配器（DAP 后端）+ 插件 UI 协同工作；按钮灰掉、断点不命中、控制台没输出，几乎全是链路断裂导致的，不是 Atom 本身坏了。
Start Debugging 按钮为什么一直是灰色？
按钮灰掉 ≠ 插件没装，而是 Atom 根本没检测到可用的 DAP 后端。常见原因包括：
- 没全局安装对应语言的调试器：
debugpy（Python）、node-debug2（Node.js），本地npm install或pip install不生效 - 插件设置里填的可执行路径错误，比如填了
/usr/local/bin/debugpy，实际在~/.local/bin/debugpy，或权限不足 - 没在项目根目录打开 Atom：
dbg-python只有在含pyproject.toml或setup.py的目录下才激活 UI - 同时启用了
atom-ide-debugger和dbg-python，两者注册冲突，DAP 客户端直接被跳过
验证方法：终端执行 debugpy --version 或 node-debug2 --version；再手动运行 debugpy --listen 5678 --wait-for-client，看 Atom 是否能 attach 上。
Python 断点打了但程序不暂停
这不是代码问题，是调试器根本没接管进程。关键在于启动方式是否真正触发 debugpy 监听：
- 必须用
python -m debugpy --listen 127.0.0.1:5678 --wait-for-client -m myproject.cli启动，不能只写python cli.py -
"module"字段必须是合法导入路径（如"myproject.cli"），不是文件路径（"./cli.py"或"cli.py"会失败） - 项目根目录必须在
PYTHONPATH中（不是当前工作目录，也不是靠sys.path.append()临时加的） -
debugpy版本建议锁定在1.6.0；1.7+ 在某些 macOS M 系列上会卡住等待 client
断点只能打在 .py 源文件里；.ipynb、.pyc、__pycache__ 下的文件不支持。
.debugger.json 配置无效的典型表现
这个文件只被 dbg-* 系列插件读取，atom-ide-debugger 完全无视它。配置错一个字就静默失效：
- 文件名必须是
.debugger.json（开头的点不能漏），且必须放在**项目根目录**，不是.atom/debugger.json或子目录 -
"type": "python"大小写敏感，写成"Type"、"PYTHON"或漏掉，整个配置被跳过 - Python 场景下
"module"填的是模块路径，不是文件路径；Node.js 场景若用"request": "attach"，必须手动填"processId"（Atom 不提供选择界面）
改完配置必须重启 Atom——插件启用后不重启，DAP 客户端根本不会注册。
JS/TS 调试别折腾插件，直接用 DevTools
Atom 本身就是 Electron 应用，所有 JS/TS 代码（包括你写的插件、UI 渲染层、甚至 Atom 自身逻辑）都跑在 Chromium 实例里：
- 按
Ctrl+Shift+I（macOS 是Cmd+Opt+I）打开的就是 Chrome DevTools -
Sources面板中展开file://或webpack://就能找到你的插件 JS 文件 - 断点设在
activate()、consumeStatusBar()这类生命周期函数里，比任何“Atom 调试插件”都准 - 主进程调试需额外指定
"program": "${workspaceFolder}/src/main-process/main.js"，但这仅适用于你正在开发 Atom 插件本身
所谓“Atom 调试 JS”，本质就是用浏览器 DevTools 调试一个跑在本地 Chromium 里的网页应用——这个事实常被忽略，却决定了最简路径。
