新插件不能直接写 index.js 是因为 Atom 插件加载器默认只识别 index.coffee 为入口，若用 Ja vaScript 必须在 package.json 中显式声明 "main"、"activationHooks" 和 "engines" 字段，否则命令注册、生命周期钩子均失效。
很多开发者习惯用 apm init 来初始化项目，但这里有个“历史包袱”：默认生成的入口文件是 index.coffee。如果你打算用 Ja vaScript 来写插件，可不能直接新建一个 index.js 就完事了。关键在于，必须在 package.json 里进行显式声明，否则你会发现，辛辛苦苦写的命令压根注册不上，插件的生命周期也完全没反应。
为什么新插件不能直接写 index.js？
问题的根源在于 Atom 的插件加载机制。它的加载器默认只认 index.coffee 这个文件名作为入口，并且会自动帮它绑定好 activationHooks 和模块路径。如果你新建了一个 lib/index.js，却忘了更新 package.json，那么接下来很可能遭遇一连串的“未解之谜”：
- 控制台抛出
Uncaught Error: Cannot find module 'my-plugin'—— 模块根本找不到。 - 按下
Cmd+Shift+P搜索，你的命令名就像消失了一样 ——activationHooks压根没触发。 - 在代码里调用
atom.commands.add时，直接报错atom is not defined—— 这是因为activate()函数在 Atom 环境初始化之前就被调用了。
说到底，Atom 不会主动去扫描 lib/ 目录下的 Ja vaScript 文件。你必须自己在 package.json 里明确指出来：
"main": "./lib/index.js"
另外，还有一个容易踩的坑：lib/ 这个目录需要你手动创建。即便你用了 apm init -p my-plugin --syntax ja vascript 命令，它也不会帮你自动生成这个文件夹结构。
package.json 里哪些字段不能省？
除了 name、version、description 这些常规字段，下面这三个配置是硬性要求，一个都不能少：
"main"：必须准确指向你实际的入口文件路径，比如"./lib/main.js"。这个字段如果留空或者写错了路径，插件就直接加载失败。"activationHooks"：必须是一个非空数组，例如["atom-workspace:pane-active"]。如果这里是空数组或者干脆缺失了，那么你的命令永远也不会被注册到系统中。"engines"：至少需要声明 Atom 的版本兼容范围，比如"atom": ">=1.7.0"。如果用户的 Atom 版本不匹配，apm在安装时就会静默失败。
这里需要特别区分一下：package.json 里的 "commands" 字段，其作用仅仅是定义菜单和快捷键的映射关系，它并不决定命令本身的功能是否可用。真正让命令生效的，是 activationHooks 的触发，以及在正确位置（activate() 函数内）执行的 atom.commands.add 调用。
命令注册后为什么还是 “command not found”？
代码明明写了，但命令面板里就是搜不到？这通常不是语法错误，而是注册的时机和作用域出了问题：
- 命令名格式必须规范：必须是
namespace:action的格式，例如"my-plugin:toggle"。如果写成"toggle"或者"myPlugin.toggle"，命令面板是不会收录的。 - 注册必须在正确时机：
atom.commands.add这个调用，必须放在插件的activate()函数体内。如果把它写在模块的顶层作用域，由于 Node 模块加载时 Atom 环境尚未就绪，就会导致注册失败。 - 作用域选择要精准：如果指定作用域为
'atom-text-editor'，那么命令只在编辑器获得焦点时生效。若希望命令全局可用，应该使用'atom-workspace'，不过这时需要注意权限和可能带来的性能影响。 - 自定义选择器需确保元素存在：如果你使用了像
'my-custom-element'这样的自定义选择器，必须确保该元素已经成功挂载到 DOM 中，否则事件监听是无效的。
下面是一个最小化的、可运行的命令注册示例（lib/main.js）：
export function activate() {
atom.commands.add('atom-text-editor', 'my-plugin:insert-timestamp', () => {
const editor = atom.workspace.getActiveTextEditor()
if (editor) editor.insertText(new Date().toISOString())
})
}
本地调试时为什么改了代码没反应？
Atom 默认不支持插件的 Ja vaScript 代码热重载。所以，每次修改代码后，你需要手动触发重载才能看到效果：
- 使用快捷键
Ctrl+Alt+Cmd+L（macOS）或Ctrl+Alt+R（Windows/Linux）来强制重载当前窗口。 - 或者，在开发者工具（DevTools）的控制台里直接执行：
atom.packages.reloadPackage('my-plugin')。 - 更稳妥的调试方式是打开两个 Atom 窗口：一个用
atom --dev命令启动，作为开发环境；另一个作为测试窗口。在开发模式下，修改并保存lib/下的文件后，按下重载快捷键，效果立刻就能呈现。
还有一个容易被忽略的细节：如果你在 activate() 函数里使用了类似 atom.workspace.onDidAddTextEditor 的异步监听器，而在插件激活的瞬间，编辑器可能还没有创建出来，那么这个回调就可能永远不会触发。稳妥的做法是，配合使用 atom.workspace.getTextEditors() 来获取已存在的编辑器实例，进行一次初始化的“补漏”操作。
