插件解压后必须放入 ~/.atom/packages（macOS/Linux）或 %USERPROFILE%.atom\packages（Windows），不可放错路径；需确保文件夹名与 package.json 中 "name" 字段完全一致，并在插件目录内执行 apm install --production 安装依赖。
插件解压后放哪？必须进 ~/.atom/packages（或 Windows 对应路径）
Atom 只扫描固定目录下的子文件夹作为插件，不是随便扔个地方就能识别。macOS/Linux 路径是 ~/.atom/packages，Windows 是 %USERPROFILE%\.atom\packages。别放进 ~/.atom 根目录，也别放进 ~/.atom/installed-packages（这目录根本不存在）。常见错误包括：解压 ZIP 后多了一层父目录（比如 atom-beautify-master/），直接把整个 atom-beautify-master 文件夹复制进去就行，不要只复制里面的内容；Windows 用户若启用了 OneDrive 同步 .atom，实际路径可能被重定向到云盘，但 Atom 启动时读的是本地路径，会导致插件不可见。
apm install --production 不执行就等于没装
GitHub 上下载的插件源码默认不含 node_modules，而 Atom 启动时不会自动运行依赖安装。直接复制文件夹重启 Atom，大概率报错 Error: Cannot find module 'season' 或 Failed to activate package 'xxx'。正确做法是：进入插件所在目录（如 ~/.atom/packages/atom-beautify），执行 apm install --production。这个命令会拉取生产依赖、执行构建脚本、生成完整可运行结构。不能用 npm install 替代——apm 和 npm 的锁版本逻辑、引擎校验、postinstall 行为都不同，漏掉 apm 特有的步骤会导致功能缺失（比如语法高亮不触发、配置面板打不开）。
插件装对了但不生效？检查激活条件和语言绑定
Atom 插件是按需加载的，不是“装完即用”。常见失效场景有：
- 打开的是纯文本文件（
.txt），但插件只在.py或.js等特定后缀下激活 - 右下角状态栏显示 “Plain Text”，没切到对应语言模式：快捷键
Ctrl+Shift+L（Win/Linux）或Cmd+Shift+L（macOS），输入语言名（如python）回车 - 插件与内置功能冲突：例如
markdown-preview-plus要求禁用 Atom 自带的markdown-preview，否则Ctrl+Shift+M无响应 -
package.json中"main"字段指向的入口文件（如"main": "./lib/main.js"）实际不存在或路径拼写错误
apm 命令找不到？PATH 和网络源要先调通
在终端里执行 apm --version 没输出，说明 apm 没进系统 PATH。macOS 运行 atom --install-shell-commands（需先从终端启动 Atom）；Windows 重装 Atom 时务必勾选 “Add to PATH”，或手动把 C:\Users\{user}\AppData\Local\atom\app-{version}\resources\app\apm\bin 加入环境变量；Linux 需确认安装的是官方 .deb/.rpm 包，并将 apm/bin 加入 $PATH。国内用户常遇到 apm install 卡在 Fetching，执行 apm config set registry https://registry.npm.taobao.org/ 换源，再验证 apm config get registry 输出是否匹配。
离线安装最易忽略的一点：必须在与目标机完全一致的 Atom 版本下执行 apm install --production。Atom 插件的 engines.atom 字段校验严格，跨版本构建的插件可能启动失败，且本体必须是官方安装包（.deb/.msi/.zip Apple 签名版），否则 apm 二进制本身可能损坏。
