插件放对位置但没反应，首要确认atom本体是否为官方安装包：windows用atomsetup-x64.exe，debian/ubuntu用atom-amd64.deb，centos/rhel用atom.x86_64.rpm，macos用apple签名的atom-mac.zip；非官方包缺失apm和签名机制，导致离线安装必然失败。
插件放对位置但没反应？先确认 Atom 本体安装方式
离线插件装不进去，90% 的问题出在 Atom 本体不是官方安装包。AtomSetup-x64.zip、.tar.gz 或第三方“绿色版”会缺失 resources/app/apm 和签名验证机制，导致 apm install 命令根本无法执行或静默失败。
必须用以下方式安装本体：
- Windows：只认
AtomSetup-x64.exe（不是 .zip） - Debian/Ubuntu：
atom-amd64.deb，运行dpkg -i - CentOS/RHEL：
atom.x86_64.rpm，用yum localinstall - macOS：
Atom-mac.zip（Apple 签名完整包，非 GitHub Release 中的源码 zip）
装完后终端执行 apm --version 能输出版本号，才算合格起点。
下载插件后别直接解压进 packages 目录
GitHub 上下载的 color-picker-master.zip 或 linter-gcc-2.0.0.zip 是源码，不是可运行副本。直接解压扔进 ~/.atom/packages/ 会导致白屏、控制台报 Cannot find module 'fs-plus' 或 Failed to activate package。
正确做法是：
- 解压后进入插件根目录（如
~/.atom/packages/color-picker） - 运行
apm install --production（不是npm install） - 检查目录下是否生成了
node_modules，且里面包含fs-plus、season等子目录 -
package.json中"main"字段必须指向真实存在的入口文件（如"./lib/color-picker.js"）
为什么用 apm install --production 而不是 npm install
apm 是 Atom 官方包管理器，它和 npm 在三方面不兼容：
- Node 版本：
apm绑定 Atom 内置 Node，npm用系统 Node，版本错位会触发gyp编译失败 - 依赖范围：
--production自动跳过devDependencies，减小体积并避免构建冲突；npm install默认全装 - 构建逻辑：某些插件（如
linter-gcc）含原生模块，apm install会自动调用node-gyp并传入 Electron 头文件路径，npm install不会
若在目标机上执行 apm install 卡住，说明网络不通——离线部署必须在**与目标机完全一致 Atom 版本**的联网机器上完成构建，再整体拷贝整个插件文件夹（含 node_modules）。
装完重启还是不生效？打开控制台看报错
不要靠“Settings → Install” 页面里有没有勾选来判断是否成功。打开开发者工具（Ctrl+Shift+I），切到 Console 标签页，常见线索有：
-
Error: Cannot find module 'season'→node_modules没生成，或apm install没执行 -
Failed to activate package 'autocomplete-python' because it depends on 'language-python@^1.0.0'→ 缺少前置语法包，需一并离线安装language-python -
Uncaught TypeError: Cannot read property 'onDidStopChanging' of undefined→ 插件构建时 Atom 版本与目标机不一致（如在 v1.72.0 下构建，却装到 v1.69.0） - 无任何报错但功能不触发 → 检查是否打开了对应后缀文件（如
.py），或右下角状态栏语言模式是否为 Python
真正麻烦的是插件激活逻辑各不相同：有的靠文件后缀，有的靠语法包加载，有的要调外部二进制（如 gopls），离线前务必在联网环境跑通一次 apm test 看它到底依赖什么。
