apm install --production是唯一可靠离线插件构建命令，必须在与目标机完全一致atom版本下执行，以生成含完整node_modules及atom特有构建产物的可运行副本。
apm install --production 是唯一可靠构建命令
离线插件不能靠“复制源码 + npm install”凑活，必须用 apm install --production 在目标环境一致的 Atom 下生成完整可运行副本。它不只是装依赖，还会执行 Atom 特有的构建逻辑（如编译 native 模块、校验 engines.atom 兼容性、注入签名验证钩子）。
常见错误包括：
- 在 v1.72.0 Atom 上构建插件，却迁移到 v1.69.0 离线机 → 激活时报
Cannot read property 'onDidStopChanging' of undefined - 用
npm install替代 → 缺少apm的 postinstall 脚本，导致linter-gcc找不到gcc子目录 - 只下载 GitHub zip 解压就扔进
~/.atom/packages/→node_modules为空，启动即报Cannot find module 'season'
正确做法：在与离线机**完全相同版本号**的 Atom（如 1.69.0）中，执行 apm install --production linter-gcc，然后确认插件目录下存在非空的 node_modules，且内含 gcc 和 atom-linter 等子目录。
Atom 本体安装方式决定离线成败
插件离线失败，80% 源于 Atom 本体本身就不合规。官方 .deb/.rpm/.exe 包自带 resources/app/apm 和签名验证机制；而 .zip 或“绿色版”会删减或损坏这些关键组件，导致后续所有 apm 命令失效。
各平台必须使用的安装包类型：
- Debian/Ubuntu：
atom-amd64.deb（dpkg -i安装，自动补libasound2等底层依赖） - CentOS/RHEL：
atom.x86_64.rpm（yum localinstall自动处理 glibc 版本） - Windows：
AtomSetup-x64.exe（AtomSetup-x64.zip是无效包，双击无响应） - macOS：
Atom-mac.zip（Apple 签名的完整包，不是 GitHub Release 里的源码压缩包）
若本体是 zip 解压硬凑的，哪怕插件目录路径全对、node_modules 齐全，控制台也会在加载阶段卡死或报 Failed to load package 'xxx'。
哪些插件根本不能离线用
不是所有插件都能离线部署。三类插件即使把整个 node_modules 拷过去，启动时仍会失败：
- 依赖实时 API：如
autocomplete-atom-api（需连接 GitHub 获取最新 API 文档）、platformio-ide（启动强制校验云端 toolchain） - 含动态下载逻辑：如某些版本的
language-rust，首次启用时拉取rustc语法定义文件 - 需要全局
apm运行时支持：如sync-settings，本质包装了apm login和apm publish，离线机从未连过服务器就无法初始化
这类插件控制台必然出现 Failed to fetch https:// 或卡在 “Loading…”，此时不必折腾构建流程，直接换替代方案（如用本地 rust-analyzer 替代 language-rust）。
插件放对了但不生效？先看 DevTools 控制台
不要凭“Settings → Install 里显示已安装”判断成功。打开开发者工具（Ctrl+Shift+I），切到 Console 标签页，关键线索就藏在第一行报错里：
-
Error: Cannot find module 'fs-plus'→ 插件根目录缺package.json，或"main"字段指向不存在的入口文件（如写成"./lib/main.js"但实际是./src/index.js） -
Failed to activate package 'linter' because it depends on 'linter@^3.0.0'→ 依赖插件（如linter）未一并离线安装，或版本号不匹配 - 无任何报错但功能不触发 → 检查是否满足激活条件（如
autocomplete-python必须打开.py文件，且language-python已加载）
真正麻烦的不是路径或命令，而是每个插件的激活时机、依赖粒度、构建产物形态都不同——minimap 需要 dist/ 目录，go-plus 要调外部 gopls，autocomplete-python 依赖 activationHooks。离线前，务必在有网机器上跑通 apm test，看清它到底依赖什么。
