apm 命令随 Atom 安装但 macOS 需手动配置 PATH：Atom → Install Shell Commands；Windows/Linux 通常可直接使用；插件安装失败多因版本不兼容，需核对 atom --version 与包页面标注的兼容版本。

apm 命令本身不是独立安装的工具，它随 Atom 编辑器一起部署；但 macOS 用户常因 Shell 命令未注册而误以为“没装好”——这不是 bug，是路径配置缺失。

apm 命令找不到？先确认 Shell 集成是否生效

Atom 1.60+ 版本在 macOS 上默认不自动写入 PATH，即使 apm -v 在终端报 command not found，也不代表 apm 不存在。

• 打开 Atom → 菜单栏 Atom > Install Shell Commands，按提示执行（需输入系统密码）
• 重启终端后运行 apm --version 验证，成功应输出类似 apm 2.6.2
• Windows / Linux 用户通常无此问题，apm 可直接调用；若失败，请检查是否以普通用户权限运行（非管理员/Root）

apm install 失败常见原因和绕过方式

报错如 No available version compatible with your Atom version，大概率不是网络或权限问题，而是插件已停止维护或版本锁死。

• 先运行 atom --version 确认当前 Atom 版本（2026 年主流为 1.60+）
• 查插件兼容性：访问 https://atom.io/packages/包名，看页面右下角 “Compatible with Atom x.y.z” 是否覆盖你当前版本
• 硬装旧版会失败：比如 apm install project-manager@1.9.0 仍会拒绝，因该包 engines.atom 字段明确限定 "
• 离线安装唯一可行路径：下载对应版本的 .tgz 包（从 GitHub Releases 或历史 archive），再用 apm install /path/to/package.tgz

apm upgrade 不更新指定包？注意默认行为差异

apm upgrade 默认只升级“有新 patch/minor 版本且满足引擎约束”的包，不会跨 major 版本升级，也不会强制覆盖被手动锁定的版本。

• 想升级某一个包：用 apm upgrade package-name，而非 apm install package-name（后者会重装，可能丢配置）
• 想跳过确认直接升级所有：加 --confirm=false 参数，例如 apm upgrade --confirm=false
• 升级失败时别急着重试：先 apm clean 清掉缓存，再 apm config list 检查是否有代理或 strict-ssl=false 类配置干扰

开发自己的包时，link 和 develop 的区别在哪

两者都用于本地调试，但作用机制完全不同，选错会导致修改不生效或 Atom 启动失败。

• apm link：把当前目录软链接到 ~/.atom/packages/your-package，Atom 启动时加载该链接。适合已完成结构、只需热改代码的场景
• apm develop package-path：在 ~/.atom/dev/packages/ 下创建副本，并启用开发模式（自动监听文件变化、禁用部分缓存）。适合从零搭建或频繁重构目录结构
• 切记：不要同时用两个命令处理同一个包；卸载时用 apm unlink your-package 或删掉 dev/packages 对应目录，别手删 packages/ 下的链接

真正容易被忽略的是 package.json 里的 engines.atom 字段——它不是建议，是硬性准入门槛。很多“安装失败”问题，根源不在 apm 或网络，而在开发者早已把包锁死在旧版 Atom 上。与其折腾兼容性，不如先看替代方案是否更轻量、更活跃。比如 project-manager 停更后，project-plus 的维护频率和 issue 响应速度明显更高。