atom --safe 是排查插件问题的首选方法，它跳过所有第三方插件和用户配置，仅加载 Atom 自带功能；若此时正常，则问题必在 ~/.atom/packages/ 或 ~/.atom/config.cson 中。
atom --safe 是插件问题的第一筛子
启动卡死、白屏、控制台刷红字，别翻日志也别重装——直接终端执行 atom --safe。它跳过所有第三方插件和用户配置，只加载 Atom 自带功能。如果这时能正常打开，问题 100% 出在 ~/.atom/packages/ 或 ~/.atom/config.cson 里。
Windows 用户必须从 CMD/PowerShell 运行，双击快捷方式无效；macOS/Linux 若提示 command not found: atom，先建软链：sudo ln -s /Applications/Atom.app/Contents/Resources/app/atom.sh /usr/local/bin/atom（路径按实际调整）。
常见误操作：
- 在安全模式下试图安装或调试插件——它只是隔离环境，不是工作环境
- 看到安全模式正常，就认为“插件没问题”，其实只是没被加载而已
- 没关掉所有 Atom 窗口（包括后台进程）就重启测试，旧 runtime 缓存仍在干扰
apm list + 倒序禁用比瞎猜快十倍
确认是插件导致后，别一个个开关。先运行 apm list --installed --packages 记下当前已装插件列表，再进 atom --safe → Settings → Packages，点右上角排序按钮，选“Last Updated”倒序排列。
优先禁用最近更新或新装的几个，尤其是这些高频出事的包：
-
linter-eslint（常因 ESLint 版本升级或.eslintrc配置错崩溃） -
vim-mode-plus（键盘事件监听冲突，易引发Cannot read property 'getSuggestions' of undefined） -
prettier-atom（格式化时调用 Node 子进程失败，报spawn ENOENT）
每禁用一个，完整退出 Atom 再重启测试。Mac 用户注意：从 Dock 点开 Atom 和从终端运行 atom，Node 环境变量可能不同，同一插件在两种方式下表现可能不一致。
控制台红字才是真凶，incompatible-packages 是个假线索
Atom 内置的 incompatible-packages 工具只检查编译兼容性，对逻辑错误、API 调用失败、模块路径写错完全无感。它不报错 ≠ 插件没问题。
真正有用的线索藏在开发者工具里：按 Ctrl+Shift+I（macOS Cmd+Option+I）打开 DevTools → Console 标签页 → 刷新 Atom → 找形如 Failed to activate package 'xxx' 或 Cannot find module 'yyy' 的报错。
这类错误常见原因：
-
package.json里"main"字段路径错误 -
activationCommands触发条件永远不满足（比如设成"core:save"却从没保存过） - 用了 Electron 不支持的语法（如顶层
await、import.meta），require阶段直接抛错，根本走不到兼容性检查环节
PATH 不生效？atom-runner 和 script 插件的根本差异
atom-runner 找不到 python 或 node 的根本原因是它不读系统 PATH，GUI 启动时未加载 shell 配置（如 ~/.zshrc），导致终端可用而 Atom 内报 command not found。
解决方式只有两条路：
- 改用
script插件（推荐），它支持填绝对路径，且设置项更透明；atom-runner已多年未维护，配置字段模糊（比如runner: python: "python"这种写法在新系统上基本失效） - 如果非要用
atom-runner，必须手动在config.cson里写死解释器全路径，例如：runner: python: "/opt/homebrew/bin/python3"（macOS）或runner: python: "C:\Users\Me\AppData\Local\Programs\Python\Python311\python.exe"（Windows） - 别信“自动检测”——
atom-runner的自动识别逻辑极弱，对虚拟环境、conda、pyenv 几乎无感 - conda / venv 环境怎么让
atom-runner正确调用？它不认激活状态，只认路径。先在终端激活环境，再执行which python（macOS/Linux）或where python（Windows），复制输出的完整路径，粘贴进config.cson的runner: python:字段，**不要加引号**（atom-runner内部不解析引号，加了反而报错）
Windows 下路径含空格导致运行失败，典型错误是填了 C:Program FilesPythonpython.exe，点击运行后面板一闪而过、无输出。这不是权限问题，是 atom-runner 把空格当成分隔符，只取了 C:Program 这一段。解决方案就一个：**绝对路径里有空格时，不要加英文双引号**。
