Hammerspoon：用 Lua 驱动 macOS 的桌面自动化神器 #

Hammerspoon 是什么？ #

Hammerspoon 是一款面向 macOS 的强力桌面自动化工具，其本质是操作系统与 Lua 脚本引擎之间的一座桥梁。它本身并不预设任何功能，而是通过一系列扩展模块，把 macOS 的应用、窗口、鼠标指针、文件系统、音频设备、电池、屏幕、键鼠底层事件、剪贴板、定位服务与 Wi-Fi 等系统能力暴露给用户。你只需在 ~/.hammerspoon/init.lua 中编写 Lua 脚本，把系统事件与自定义动作连接起来，就能实现快捷键组合窗口操作、联网时自动执行命令、电量低于阈值时弹出提醒等自动化场景。它适合愿意投入一点学习成本、追求高度个性化工作流的 Mac 用户。

Hammerspoon 有哪些亮点特色？ #

• Lua 脚本即一切：Hammerspoon 不提供图形化的规则编辑器，而是把完整的 Lua 脚本语言交到用户手中，配合标准 Lua API 与 Hammerspoon 自有 API，几乎可以表达任意自动化逻辑，自由度远超普通快捷指令工具。
• 深度桥接 macOS 系统 API：官方文档列出上百个模块，覆盖 hs.application（操纵运行中的应用）、hs.window（窗口控制）、hs.eventtap（键鼠事件拦截与改写）、hs.audiodevice（音频设备）、hs.battery（电池状态）、hs.location（定位服务）、hs.wifi（无线网络）等，几乎把桌面系统的每一层都暴露为可编程接口。
• 事件驱动的自动化范式：典型用法是在配置文件中把事件绑定到动作，例如将快捷键绑定到一串窗口操作或 AppleScript，在 Wi-Fi 接入家庭网络时执行一段命令，或在电量跌破某一百分比时弹出告警，真正做到"系统状态一变，脚本即响应"。
• Spoons 预制插件生态：官方提供名为 Spoons 的现成插件库，用户无需从零编写脚本，直接引入社区打磨好的功能模块即可扩展 Hammerspoon 的能力，大幅降低了上手门槛。
• 可扩展至 Objective-C 层：除了纯 Lua 辅助脚本，开发者还能编写 Objective-C 扩展，把尚未暴露的系统功能接入 Hammerspoon，让工具的能力边界随社区贡献持续生长。
• 完全开源且社区活跃：项目托管于 GitHub，提供 Discord 服务器、Google 邮件列表与 Issue Tracker 等支持渠道，文档、API 参考与发布说明齐全，用户遇到问题可快速获得帮助。
• 轻量无捆绑，默认零打扰：安装包体积仅约 9 MB，开箱即用时不执行任何动作，只有在用户主动编写脚本后才会工作，不会在后台制造无谓干扰。

免费下载 Hammerspoon #

以下为官方发布的 macOS 安装包，点击链接即可下载。当前版本为 1.1.1，要求 macOS 13.0 及以上系统。

Hammerspoon 如何使用？ #

1. 首次启动并授权：将 Hammerspoon 拖入 /Applications/ 后启动。由于它依赖 macOS 的辅助功能（Accessibility）接口与桌面交互，需要前往「系统设置 → 隐私与安全性 → 辅助功能」，勾选 Hammerspoon 以授予权限。
2. 创建配置文件：Hammerspoon 开箱后不会做任何事。你需要在 ~/.hammerspoon/init.lua 中编写 Lua 脚本，使用 Hammerspoon API 与标准 Lua API 描述你的自动化逻辑。首次启动时应用通常会自动创建该目录。
3. 打开控制台调试：菜单栏图标中可打开 Hammerspoon Console，用于实时执行 Lua 片段、查看日志输出与调试脚本，是学习 API 的重要工具。
4. 绑定快捷键与事件：借助 hs.hotkey 创建全局快捷键，或使用 hs.application.watcher、hs.battery.watcher、hs.wifi.watcher 等监视器模块，把系统事件与自定义动作连接起来。
5. 引入 Spoons 扩展：访问官方 Spoon 仓库下载现成插件，将其放入 ~/.hammerspoon/Spoons/ 目录，并在 init.lua 中加载，即可复用社区功能而无需自己编写全部逻辑。
6. 重新加载配置：修改 init.lua 后，可通过菜单栏的 Reload Config 或快捷键快速重载，让新配置立即生效，无需重启应用。

对于新手，建议先阅读官方的 Getting Started Guide，并对照完整 API 文档逐步尝试。

Hammerspoon 的常见问题？ #

Hammerspoon 会收集崩溃信息吗？ 默认会收集，但可以在 Hammerspoon 的偏好设置中关闭。官方在隐私政策中说明了相关数据的处理方式。

为什么必须手动授予辅助功能权限？ Hammerspoon 依赖 macOS 的辅助功能栈来与桌面交互，受限于系统的安全要求，用户必须手动在「系统设置 → 隐私与安全性 → 辅助功能」中将 Hammerspoon 加入列表并勾选，否则无法正常工作。

无法把 Hammerspoon 加入辅助功能列表或无法启用怎么办？ 这通常意味着控制辅助功能权限的数据库出现了不同步或 Launch Services 数据库损坏。可参考官方给出的恢复指南，或使用终端命令 sudo /System/Library/Frameworks/CoreServices.framework/Versions/Current/Frameworks/LaunchServices.framework/Support/lsregister -kill -r -domain local -domain system -domain user 强制重建数据库。

升级到 Catalina 后 Hammerspoon 不再向其他应用发送按键？ 可在终端中执行 tccutil reset All org.hammerspoon.Hammerspoon 重置 Hammerspoon 的全部权限，然后重新授权即可恢复。

脚本中获取到的应用名称和预期不一致？ 部分应用（如 Microsoft Office 系列）向系统报告的名称与菜单栏显示的名称不同。例如查找 Word 时应使用 "Microsoft Word" 而非 "Word"。可通过 hs.application.runningApplications() 遍历打印应用真实名称来确认。

全屏应用下不显示图形或 UI 元素？ 这是启用 Dock 图标时已知的问题。可在偏好设置中取消勾选 "Show dock icon"，或在 init.lua 中加入 hs.dockIcon(false) 来解决。

可以给 Hammerspoon 开发者捐款吗？ 官方表示不接受金钱捐赠，而是希望用户按照自己认为 Hammerspoon 的价值，将等额款项捐给自选的慈善机构。

Hammerspoon 如何安装？ #

Hammerspoon 目前仅支持 macOS，安装步骤非常简单：

1. 确认系统版本：1.1.1 版本要求 macOS 13.0 及以上。若你的 Mac 运行的是较旧版本的 macOS，请查阅官方 Release Notes 选择兼容的历史版本（例如 1.0.0 要求 macOS 12.0、0.9.100 要求 macOS 11.0）。
2. 下载安装包：从上方下载表格获取 Hammerspoon-1.1.1.zip，下载完成后解压。
3. 拖入应用程序目录：将解压得到的 Hammerspoon.app 拖拽到 /Applications/ 目录中，即完成安装。
4. 首次启动授权：打开 Hammerspoon，按提示前往「系统设置 → 隐私与安全性 → 辅助功能」授予其辅助功能权限，否则脚本无法与桌面交互。
5. 可选：通过 Homebrew 安装：习惯命令行的用户也可以使用 brew install --cask hammerspoon 完成安装与后续升级。

注意：早期版本的下载压缩包中可能包含会干扰 macOS Gatekeeper 的多余资源分支文件，官方已在 1.1.1 中修复该问题，建议优先使用最新版本。

Hammerspoon 如何卸载？ #

在 macOS 上卸载 Hammerspoon 可按以下步骤操作：

1. 退出应用：点击菜单栏的 Hammerspoon 图标，选择 Quit 退出程序。
2. 删除主程序：打开「访达 → 应用程序」，将 Hammerspoon.app 拖入废纸篓，或右键选择「移到废纸篓」。
3. 清理用户配置目录（可选）：Hammerspoon 的脚本与个人配置保存在 ~/.hammerspoon/ 目录中，包括 init.lua 与 Spoons 插件。如不再使用，可在终端执行 rm -rf ~/.hammerspoon 彻底删除。
4. 清理偏好设置（可选）：若希望清除全部应用偏好，可在终端执行 defaults delete org.hammerspoon.Hammerspoon（如无该域则忽略报错）。
5. 移除辅助功能授权：前往「系统设置 → 隐私与安全性 → 辅助功能」，选中 Hammerspoon 后点击减号将其移除，避免残留的授权条目。

完成上述步骤后，Hammerspoon 即被完整卸载。如仅想暂时停用，也可以仅退出应用并取消辅助功能勾选，而保留配置文件以便日后恢复使用。