Atom插件安装失败主因是apm未接入registry或未加入PATH；国内需切换taobao registry；原生插件须用apm rebuild重编译；离线安装须在同版本Atom联网机执行apm install。
插件装不上，八成不是网络断了，而是 apm 根本没连上可用 registry，或者根本没进系统 PATH。
apm 命令报 command not found
这是 Windows/macOS/Linux 上最常卡住的第一步。Atom GUI 启动不继承终端环境变量，所以即使你在终端里能跑 apm --version，Settings → Install 里照样搜不到插件。
- Windows：重装 Atom 时务必勾选 “Add to PATH”；若已安装，手动把
C:\Users\{用户名}\AppData\Local\atom\app-{version}\resources\app\apm\bin加进系统环境变量 PATH - macOS：在终端运行
atom --install-shell-commands（需先通过终端启动一次 Atom），然后重启终端 - Linux：用官方
.deb或.rpm包安装，确保/usr/bin/apm是软链到 Atom 自带的 apm 二进制
apm install 卡在 fetching… 或报 ENOTFOUND/ETIMEDOUT
这不是你本地网络问题，是 apm 默认 registry https://registry.npmjs.org/ 在国内基本不可达。所有搜索为空、安装超时、apm search 返回空列表，都指向这个根源。
- 执行
apm config set registry https://registry.npm.taobao.org/（注意：不是npm config） - 验证：运行
apm config get registry，输出必须是刚设的地址 - 改完必须运行
apm install --check，看到Checking for native build tools done才算真正就绪 - 别碰
.apmrc文件——路径错（比如放错目录）、格式错（多空行、BOM、中文标点）、字段错（写proxy或https-proxy）都会静默失效
插件显示“已启用”但功能不生效
常见于 linter、spell-check、term3 这类含原生模块的插件。Atom 自带独立 Node（v12.x/v14.x），不认系统 Node 编译的模块。
- 打开 DevTools（
Ctrl+Shift+I），输入process.versions.node确认当前内置 Node 版本 - 关掉所有 Atom 窗口（包括后台进程），再运行
apm rebuild—— 这会强制用 Atom 内置 Node 重编译所有包 - 别用
npm rebuild，它调的是系统 Node，完全无效 - 如果
apm rebuild报 zlib 错误，说明缓存损坏，先跑apm clean再重来
离线环境插件复制后仍不加载
直接把 GitHub 源码解压进 ~/.atom/packages/ 是无效操作。Atom 不会自动执行 npm install，缺 node_modules 就必然报 Cannot find module 'season' 之类错误。
- 必须在与目标机**完全一致 Atom 版本**的联网机器上，运行
apm install --production linter-gcc（以linter-gcc为例） - 检查插件目录下是否存在
node_modules，且里面包含对应依赖（如gcc、atom-linter） - Atom 本体必须用官方安装包：
AtomSetup-x64.exe（Windows）、atom-amd64.deb（Debian/Ubuntu）、atom-mac.zip（macOS，注意是 Apple 签名版） - 某些插件根本不能离线用，比如
autocomplete-atom-api（需实时拉 GitHub API 文档）、platformio-ide（启动强制校验云端 toolchain）
最容易被忽略的一点：插件是否激活，不只看 Settings 里有没有勾，得看控制台报错。打开 Ctrl+Shift+I → Console，第一眼就该扫 Error: 和 Failed to activate package——这些线索比“看起来装好了”可靠得多。
