Atom菜单栏需编辑对应系统的CSON文件（darwin.cson/macOS、linux.cson/Linux、win32.cson/Windows），command须为已注册标识符，上下文菜单依赖CSS选择器，动态回调须用CoffeeScript语法且同步执行。

Atom

的菜单栏不能通过 UI 界面直接拖拽或点击添加，必须编辑 CSON 配置文件。你改的是哪一层菜单，决定了生效范围和平台兼容性—— macOS、Linux、Windows 各自用不同文件，改错一个就只在对应系统起作用。

修改哪个文件：darwin.cson / linux.cson / win32.cson？

菜单配置按操作系统拆分，路径统一在 menus/ 目录下：

• menus/darwin.cson：仅 macOS 生效，含「服务」「访达」等原生集成项
• menus/linux.cson：仅 Linux 桌面环境（如 GNOME、KDE）生效
• menus/win32.cson：仅 Windows 生效，注意它不处理 Win11 的新式上下文菜单

如果你加的菜单想跨平台，得三份文件都同步改；如果只是临时调试，优先改当前系统对应的那份。别试图把所有平台配置塞进一个文件——Atom 启动时只加载匹配平台的那个。

菜单项 command 必须已注册，否则点击无响应

写进 label 和 command 很容易，但 command 值不是随便起的字符串，它必须是 Atom 内部已注册的命令标识符，比如 core:save、application:open，或者你自己的包里通过 atom.commands.add 注册过的，例如 my-package:toggle-panel。

• 查已有命令：按 Cmd+Shift+P（macOS）或 Ctrl+Shift+P（Win/Linux），输入「Command Palette」，就能看到全部可用命令列表
• 自定义命令未激活：即使 package.json 里声明了 commands，也得确保包已启用，且 activate() 中调用了 atom.commands.add
• 拼写大小写敏感：core:Save ≠ core:save，后者才有效

上下文菜单选择器写错，菜单根本不会出现

上下文菜单靠 CSS 选择器触发，不是靠文件类型或路径。常见错误是选错了目标元素：

• 'atom-text-editor'：只对编辑器内容区右键生效，不对侧边栏、状态栏、空白区域起作用
• 'atom-workspace'：整个窗口区域，但右键时可能被更具体的选择器（如 atom-pane）覆盖
• 'atom-pane .item-views'：精准到面板内的视图容器，适合插件 UI 集成
• 多个选择器用逗号分隔：'atom-text-editor, .overlayer' 是合法的，但中间不能有空格
• 带语法过滤的选择器要加引号：'[data-grammar~="source.js"]'，漏掉引号会解析失败

调试技巧：打开开发者工具（Cmd+Alt+I），右键目标区域，检查最外层 DOM 元素的 class 和属性，再反推选择器怎么写。

动态菜单项 created/shouldDisplay 回调里的 event 对象不可序列化

这两个函数在菜单弹出前执行，常被用来做「当前是否有选中文本」「光标是否在注释内」等判断。但要注意：event 参数是原生 DOM 事件，里面含大量循环引用对象（如 target.ownerDocument），不能直接 JSON.stringify 或存入 config。

• shouldDisplay 返回 false 时，菜单项彻底不显示，不是灰掉
• created 里可动态改 label 或加 icon，但不能异步等待 Promise——回调必须同步返回
• 获取当前编辑器实例推荐用：atom.workspace.getActiveTextEditor()，而不是从 event.target 硬扒

最容易忽略的一点：这些回调函数写在 CSON 文件里时，必须用 CoffeeScript 语法（哪怕你其他地方全用 JS），因为 CSON 解析器只认 CoffeeScript 函数字面量。写成 ES6 箭头函数会静默失败。