hammerspoon.org

Hammerspoon是什么网站?

Hammerspoon 是一个面向 macOS 的桌面自动化工具，官网是 Hammerspoon。它的核心是“操作系统与 Lua 脚本引擎之间的桥”：用 Lua 写配置，把系统事件和你想执行的动作连起来。

它能做什么

根据官网说明，你可以用 Lua 与 macOS 的多种 API 交互，覆盖：

• 应用、窗口、鼠标指针
• 文件系统对象、剪贴板
• 音频设备、屏幕、电池
• 键盘/鼠标的底层事件
• 位置服务、Wi-Fi

典型用法是写一个 ~/.hammerspoon/init.lua 配置文件，把事件绑定到动作上。例如：

• 给某个快捷键绑定一串窗口操作，或运行一段 AppleScript
• 当 Wi-Fi 连上家里网络时自动执行一组命令
• 电量低于某个百分比时弹出提醒
• 更“折腾”的玩法，比如检测到你在巴黎时自动让 iTunes 播放

适合谁、什么场景用

适合愿意写脚本、想深度定制 macOS 行为的人，而不是想装完即用的普通工具。官网明确说：开箱后 Hammerspoon 什么都不做，必须自己写 Lua 脚本。

如果你只想快速加几个现成功能，可以先看它预制的插件 Spoons；想从头学，则读 Getting Started Guide 配合完整 API 文档。安装方式是下载最新版，把应用拖进 /Applications/；老版本 macOS 需要查 Release Notes 找兼容版本。

和类似工具比，侧重点在哪

它和 Raycast、Keyboard Maestro 的取向不同：后两者偏向开箱可用的启动器或图形化自动化，Hammerspoon 则把控制权交给 Lua 代码，灵活度更高，但需要自己写和维护脚本。想要“少配置、多现成功能”，选前者；想要“任何系统事件都能接进自己的逻辑”，Hammerspoon 更合适。

Hammerspoon可以用于哪些macOS自动化场景?

Hammerspoon 是一个把 macOS 系统接口和 Lua 脚本引擎连接起来的自动化工具，开箱时本身不做任何事，能力来自它暴露的各类系统扩展和用户自己写的 ~/.hammerspoon/init.lua。所以它的适用场景，基本取决于你想把哪些系统事件接到哪些动作上。

常见自动化场景

• 窗口与应用管理：把快捷键绑定到一系列窗口操作，例如快速移动、缩放、切换应用窗口。
• 键盘与鼠标事件：处理低层键盘、鼠标事件，做自定义快捷键或输入触发逻辑。
• 网络状态触发：当 Wi-Fi 连接到家里的网络时，自动执行一串命令。
• 电源与电池提醒：电量低于设定百分比时弹出提醒。
• 音频与设备控制：与音频设备等系统功能交互，做音量、输出设备的自动切换。
• 剪贴板与文件系统：围绕剪贴板内容、文件系统对象编写自动化处理。
• 位置服务：结合位置信息触发动作，例如资料里提到的“检测到你在巴黎就自动播放 iTunes”这类玩法。
• 调用 AppleScript：把快捷键或事件接到 AppleScript 上，串联已有的 Mac 自动化流程。

谁适合用

适合愿意写一点 Lua、又需要深度控制 macOS 的用户，比如想让窗口布局、网络切换、电量提醒都按自己的规则跑起来的人。如果只是想要现成功能，可以先看官方推荐的预置插件 Spoons，它们是用 Lua 写好的可复用模块，能省去从零写脚本的步骤。

上手路径

1. 下载最新版，把应用拖进 /Applications/；旧版 macOS 需先查 Release Notes 找兼容版本。
2. 阅读 Getting Started Guide，对照完整 API 文档。
3. 在 ~/.hammerspoon/init.lua 里把事件和动作连起来。
4. 想扩展功能，可以写纯 Lua 辅助脚本，也可以用 Objective-C 写扩展暴露新的系统能力。

和其他工具相比的侧重点

Hammerspoon 的重点是“用 Lua 直接桥接 macOS API”，灵活度和可编程性高，代价是需要自己写配置。若你更想要开箱即用的窗口管理，可以对比 Rectangle；若偏向图形化、模块化的自动化流程，可看 Alfred 或 Keyboard Maestro。选择时先问自己：是要写代码换最大自由度，还是要现成界面换更低上手成本。

如何安装Hammerspoon?

安装 Hammerspoon 很简单：从官网下载最新版，把应用拖进 /Applications/ 就行。装好后它默认什么都不做，需要你自己在 ~/.hammerspoon/init.lua 写 Lua 脚本才会开始工作。

具体步骤

1. 打开 Hammerspoon 官网，点击 Download 下载最新 release。
2. 把下载到的应用拖入 /Applications/ 文件夹。
3. 首次启动后，创建配置文件 ~/.hammerspoon/init.lua，用它的 API 和标准 Lua 写自动化逻辑。

适用场景与注意点

• 如果你的 Mac 系统版本较旧、跑不了最新版，先查官网 Release Notes，找与你系统兼容的版本再装。
• 新手建议先读 Getting Started Guide，配合完整 API 文档；想直接用现成功能可以看 Spoons（预制插件）。
• 典型用法是“把事件连到动作”，例如：给一组窗口操作绑定快捷键、连上家里 Wi-Fi 时自动跑一串命令、电量低于某比例时弹提醒。

和同类工具的选择

Hammerspoon 的定位是“操作系统与 Lua 引擎之间的桥”，靠扩展暴露系统功能，适合愿意写脚本、想要深度定制 macOS 自动化的人。如果你只想点几下配置快捷键、不打算写代码，它可能偏重；愿意用 Lua 换取对窗口、键鼠事件、Wi-Fi、电池、剪贴板等系统层面的控制，它就很合适。

Hammerspoon的配置文件init.lua应该放在哪里?

Hammerspoon 的配置文件 init.lua 应放在用户主目录下的 .hammerspoon 文件夹中，完整路径是：

~/.hammerspoon/init.lua

~ 代表你的用户主目录（通常是 /Users/你的用户名）。Hammerspoon 启动时会自动读取这个文件；如果文件不存在，软件不会报错，但也不会执行任何自动化操作，即官网所说的“开箱即用状态下它什么都不做”。

使用要点

• 目录不存在就手动创建：如果 ~/.hammerspoon/ 文件夹还没有，需要自己新建，再把 init.lua 放进去。
• 文件名必须是 init.lua：这是默认入口文件，写其他名字不会被自动加载。
• 写完后重新加载：在菜单栏 Hammerspoon 图标里选择 Reload Config，或使用默认的重新加载快捷键，让改动生效。
• 内容用 Lua 编写：文件里写的是 Lua 代码，通过 Hammerspoon 的 API 把系统事件和动作连接起来。官网建议新手对照 Getting Started Guide 和完整 API 文档来写。

典型场景

例如你想给一组窗口操作绑定一个快捷键，或让 Wi-Fi 连接到家里网络时自动执行一串命令，这些逻辑都写在 ~/.hammerspoon/init.lua 里。Hammerspoon 本身只是操作系统与 Lua 引擎之间的桥梁，真正做什么由这个文件决定。

如果不想从零写，可以先看官方提供的预制插件 Spoons，把它们的配置片段加进 init.lua 调用即可。

Spoons是什么,如何获取和使用?

Spoons 是 Hammerspoon 的预制插件（插件/模块），用 Lua 写成，封装了常见自动化需求，省去从零写代码。官方页面把它与入门指南、完整 API 文档并列，作为探索 Hammerspoon 能力的入口。

获取方式

• 从 Hammerspoon 官网的 Spoons 页面查看和下载现成插件。
• 安装 Hammerspoon 后，把 Spoon 放到 ~/.hammerspoon/Spoons/ 目录下（每个 Spoon 是一个 .spoon 文件夹）。
• 也可通过社区仓库、GitHub 搜索他人分享的 Spoon。

使用方式

在 ~/.hammerspoon/init.lua 中加载并启动：

hs.loadSpoon("SpoonName")
spoon.SpoonName:start()

具体配置项因 Spoon 而异，需查看该 Spoon 自带的文档或 README。Hammerspoon 开箱即用时不执行任何操作，必须自己写 init.lua，Spoon 只是帮你少写这部分。

适合谁、什么场景用

• 想快速实现窗口管理、快捷键绑定、Wi-Fi 连接触发动作、电量提醒等，但不想读完整 API 自己造轮子的人。
• 想参考别人写法学习 Hammerspoon 用法的新手。
• 已有需求较特殊、找不到对应 Spoon 时，仍需自己写 Lua 或写 Objective-C 扩展。

和直接写脚本的区别

Spoon 是打包好的 Lua 模块，提供 start()、stop()、bindHotkeys() 等统一接口；自己写脚本则完全自由，但要从头处理加载、配置和生命周期。两者可混用：加载 Spoon 后仍能在 init.lua 里覆盖或补充逻辑。

下一步

先装好 Hammerspoon，创建 ~/.hammerspoon/init.lua，从官网 Spoons 列表挑一个匹配你需求的插件，按它的说明加载并运行。遇到问题可在 Hammerspoon 的 Discord 或 GitHub issue tracker 求助。想深入可参考 Lua 官网 学语言基础。

Hammerspoon遇到问题可以去哪里寻求帮助?

Hammerspoon 遇到问题，优先去官方 Discord 服务器，其次是 GitHub issue tracker。

具体渠道

• Discord 服务器：官方页面明确写了“We have a Discord server to chat about Hammerspoon”，适合提问、交流用法、找人帮忙排查配置。
• GitHub issue tracker：遇到 bug 或有功能建议时使用。官网说明，网站本身的问题也可以在 GitHub 报告。
• 官方文档：先查 Getting Started Guide 和完整 API Documentation，再去看 Spoons 里现成的插件，很多问题能自己解决。

怎么选

提问前建议

Hammerspoon 默认什么都不做，所有行为都来自 ~/.hammerspoon/init.lua 里的 Lua 脚本。提问时附上相关配置片段、macOS 版本和复现步骤，更容易得到有效回复。