直接解压进~/.atom/packages失败，因Atom不接受源码态插件：需在同版本Atom下运行apm install --production生成node_modules及lib/等构建产物，并确保文件夹名与package.json中"name"完全一致。
离线安装 Atom 插件到 packages 目录，光复制代码文件夹进去是没用的——node_modules 缺失、入口文件未构建、依赖版本不匹配，都会导致插件加载失败或控制台报 Cannot find module 'xxx'。
为什么直接解压进 ~/.atom/packages 大概率失败
常见错误现象包括：重启 Atom 后插件不显示、设置页里搜不到、开发者工具（Ctrl+Shift+I）报 Error: Cannot find module 'season' 或 Failed to activate package 'linter-gcc'。根本原因不是路径放错，而是 Atom 不接受“源码即插件”：它只加载已执行过构建流程、含完整 node_modules 和可运行产物（如 lib/main.js）的目录。
- GitHub 上下载的 zip 包或
git clone的内容默认不含node_modules，Atom 启动时不会自动补装 -
package.json中的"main"字段若指向不存在的文件（比如写成./src/index.js但实际只有./lib/main.js），插件根本不会初始化 - 文件夹名必须与
package.json中的"name"完全一致（大小写敏感），否则 Atom 扫描时直接跳过
必须在同版本 Atom 下运行 apm install --production
不能用 npm install 替代，也不能在任意 Node 环境下构建。Atom 插件依赖 apm 特有的解析逻辑、引擎校验（engines.atom）、以及可能的 native 模块编译（如 linter-gcc 调用 gcc 的 binding）。
- 目标离线机是 Atom v1.69.0，则构建机也必须是 **完全一致的 v1.69.0**（通过官方
.deb/.msi安装，禁用 zip 解压版） - 进入插件目录后，运行
apm install --production（--production关键：跳过devDependencies，避免体积膨胀和构建失败） - 执行后检查目录下是否存在
node_modules，且里面包含该插件真正 require 的模块（如linter-gcc需要gcc、atom-linter子目录） - Windows 用户注意：确保
C:Users\AppDataLocaltomin和app-1.x.x esourcespppmin都已加入系统 PATH，否则apm命令不可用或构建失败
拷贝前确认三件事：路径、结构、依赖
把构建好的整个插件文件夹（例如 ~/.atom/packages/linter-gcc）整体打包迁移到离线机，不是只复制源码子目录。
- 目标路径必须是 Atom 默认扫描路径：
~/.atom/packages（Linux/macOS）或%USERPROFILE%.atompackages（Windows），不能放在~/.atom根目录或云同步文件夹（如 OneDrive 下的 .atom） - 解压后不能多一层父目录（如
linter-gcc-master/），必须是linter-gcc/直接位于packages/下 - 某些插件有硬依赖，比如
autocomplete-python必须搭配language-python，两者都要按同样流程离线构建并一起拷过去；缺一个，补全功能就起不来
不是所有插件都能离线用，先看控制台报错再动手
即使 node_modules 齐全、路径正确，有些插件启动时仍会卡住或报 Failed to fetch https://...——这类插件本质上无法离线。
- 依赖实时 API 的：如
autocomplete-atom-api（需连 GitHub 获取最新文档）、platformio-ide（强制校验云端 toolchain） - 含动态下载逻辑的：如部分
language-rust版本会在首次启用时拉取语法定义文件 - 需要全局
apm运行时的：如sync-settings，离线机从未apm login就无法初始化
装完不确定是否生效？打开开发者工具 → Console 标签页，重点盯 Cannot read property 'onDidStopChanging' of undefined（版本不匹配）、Failed to load package 'xxx' because it's incompatible（Atom 版本或依赖冲突）这类错误——它们比“插件没出现在列表里”更早暴露真实问题。
