先确认是否装对了包：必须安装 atom-ide-ui 维护的 tool-bar（≥1.4.0），而非已停更的 atom-toolbar-config；tool-bar 本身不提供按钮，需依赖 script、git-plus 等插件注册命令，且命令须在 package.json 的 commands 字段声明或通过 atom.commands.add 正确注册。
tool-bar 插件没反应？先确认是否装对了包
很多人装完 tool-bar 发现顶部没出现工具栏，第一反应是“坏了”，其实大概率是装错了包。Atom 社区有两个名字接近但完全不同的插件：tool-bar（由 atom-ide-ui 团队维护）和更早的 atom-toolbar-config（或 atom-toolbar-almighty）。前者轻量、只负责渲染按钮，不带配置界面；后者功能强但已多年未更新，容易和 Atom 1.60+ 的 API 冲突。
正确做法是：在 Settings → Packages 页面搜索 tool-bar，认准作者是 atom-ide-ui，版本号 ≥ 1.4.0。如果看到的是 atom-toolbar 或 atom-toolbar-almighty，建议卸载，再重装 tool-bar。
- 装错包的典型现象：
tool-bar激活后无报错，但 DOM 中找不到.tool-bar元素 -
tool-bar本身不提供按钮逻辑，所有按钮都靠其他插件“注册”——比如script插件会自动注册“运行当前文件”按钮，git-plus注册 Git 操作按钮 - 如果你只装了
tool-bar，没装任何能触发它的功能插件，工具栏就是空的，这属于正常行为，不是 bug
怎么让自定义命令出现在工具栏里
想加个“保存并格式化”的按钮，但发现 tool-bar 不认你写的命令？关键在于命令注册方式必须符合它的发现机制。
tool-bar 只识别两类命令：
- 已安装插件在
package.json的commands字段中声明的命令（如atom-beautify:format） - 通过
atom.commands.add注册、且命名空间与已有插件一致的命令（比如你仿script插件写script:run）
直接在 DevTools 控制台执行 atom.commands.dispatch 或用 atom.packages.activatePackage 手动加载的命令，tool-bar 是看不到的。
实操建议：
- 优先用现成插件的命令 ID，比如
core:save、editor:toggle-line-comments、atom-beautify:format - 若需组合操作（如保存 + 格式化），不要自己写新命令，改用
atom-shell-commands或platformio-ide-terminal绑定 shell 脚本 - 检查命令是否真被注册：打开 Command Palette（
Ctrl+Shift+P），搜一下命令名，能搜到才说明tool-bar有可能识别它
tool-bar.json 配置文件放哪儿、怎么写才生效
tool-bar 默认不读取外部 JSON 配置——它没有内置配置文件支持。所谓 “tool-bar.json” 实际是老版 atom-toolbar-config 的用法，混用会导致工具栏重复渲染或样式错乱。
当前版本（≥1.4.0）唯一支持的配置方式是通过 config.cson 设置 tool-bar 的显示行为：
- 路径：
~/.atom/config.cson（macOS/Linux）或%USERPROFILE%\.atom\config.cson（Windows） - 关键字段：
"tool-bar"下的showToolBar（布尔值）、position（"top"或"bottom"）、iconSize（像素值） - 按钮顺序、分组、图标等高级定制，必须靠插件自身支持，
tool-bar不提供排序 API
常见错误：
- 新建
~/.atom/tool-bar.json并期待它被自动加载 —— 不会生效 - 在
config.cson里写buttons: [...]—— 这个字段已被移除，Atom 启动时会忽略并报 warning - 以为改了
iconSize就能换图标字体 —— 图标来源取决于各插件自己的 CSS，tool-bar只控制尺寸和间距
工具栏图标模糊、点击无响应？查这几个地方
图标糊成一团或点不动，通常不是 tool-bar 本身的问题，而是上下游链路断了。
- 图标模糊：多数因插件用了 SVG 但没设
width/height，或 Atom 主题 CSS 覆盖了font-size。临时解法是在styles.less里加：.tool-bar .btn { font-size: 14px; } - 点击无响应：先看浏览器开发者工具 Elements 面板，检查按钮元素是否有
disabled属性或pointer-events: none；再查 Console 是否有Uncaught TypeError: Cannot read property 'dispatch' of undefined—— 这说明对应插件没激活或已崩溃 - 工具栏位置错位（比如卡在编辑器中间）：通常是某插件注入了绝对定位的 DOM，干扰了
tool-bar的 flex 布局。可临时禁用最近安装的插件逐个排查
最常被忽略的一点：tool-bar 渲染依赖 Atom 的 workspace 生命周期，如果某个插件在 deactivate() 里没清理好事件监听器，会导致后续工具栏按钮绑定失效——这种问题重启 Atom 也不解决，必须手动删掉 ~/.atom/packages/xxx 再重装。
