1. 项目概述一个解决 macOS 用户“痛点”的小工具如果你是一名 macOS 用户并且经常需要长时间离开电脑但又不想让系统进入睡眠状态或触发屏幕保护程序那么你很可能遇到过这样的困扰正在进行的下载、渲染、编译或者远程连接因为系统误判你“已离开”而中断。我最初注意到ansh-info/move-mouse-macOS这个项目就是因为它精准地瞄准了这个看似微小、实则恼人的需求。这并非一个复杂的系统级应用而是一个用 Swift 编写的、功能极其聚焦的命令行工具——它的核心使命只有一个自动、可控地模拟鼠标移动从而“欺骗”系统使其保持活跃状态。在 macOS 的开发或日常使用场景中系统基于用户活动键盘、鼠标、触控板输入来判断是否空闲。一旦超过设定的时间便会启动屏幕保护、降低亮度甚至进入睡眠。虽然系统偏好设置中提供了相关选项但很多时候我们需要更灵活、更临时的控制。比如在服务器端执行一个长达数小时的脚本时你希望 Mac 保持唤醒但又不希望修改全局的节能设置或者在进行视频会议共享屏幕时需要防止屏幕变暗。手动时不时晃动鼠标显然不是优雅的解决方案。move-mouse-macOS的出现提供了一种轻量级、可编程的自动化手段。这个项目本质上是一个“防休眠”或“保活”工具。它通过编程方式向系统发送模拟的鼠标移动事件让系统认为用户仍在操作从而阻止其进入休眠或屏保状态。对于开发者、设计师、视频工作者或者任何需要 Mac 长时间执行任务而不被中断的用户来说这是一个实用价值很高的小工具。它的代码仓库结构清晰采用 Swift 编写天然与 macOS 系统集成良好避免了跨平台工具可能存在的兼容性问题。接下来我将深入拆解这个工具的设计思路、核心实现、使用方法以及我本人在实际部署和扩展过程中积累的一些经验。2. 核心原理与系统交互机制要理解move-mouse-macOS如何工作首先需要了解 macOS 是如何处理用户输入和系统电源管理的。macOS 的核心框架之一是IOKit和Quartz Event Services。我们的鼠标、键盘等输入设备产生的信号最终会通过这些框架转化为系统能够理解的CGEventCore Graphics Event。系统电源管理守护进程powerd则会监听这些事件的发生频率。当在一段时间内没有检测到新的 CGEvent它就会按照预设的策略逐步执行降低屏幕亮度、启动屏保、进入睡眠等操作。2.1 模拟输入事件的核心 APImove-mouse-macOS工具的核心在于调用Quartz Event Services中的CGEventCreateMouseEvent和CGEventPost这两个关键函数。CGEventCreateMouseEvent: 这个函数用于创建一个新的鼠标事件。你需要告诉它事件类型是鼠标移动kCGEventMouseMoved、左键按下kCGEventLeftMouseDown还是其他。事件发生的位置以屏幕坐标CGFloat表示。鼠标按钮状态对于移动事件通常传入kCGMouseButtonLeft或kCGMouseButtonCenter等但实际移动事件不依赖按钮状态。CGEventPost: 创建事件后需要将其“投递”到系统的事件流中。这里通常使用CGEventPost(.cghidEventTap, event)。cghidEventTap表示将事件投递到系统底层的人机接口设备HID事件流这模拟了真实硬件产生的输入因此能够有效地被电源管理系统识别。通过周期性地例如每隔 55 秒创建一个将鼠标移动到当前位置附近比如偏移 1 个像素的kCGEventMouseMoved事件并投递工具就能持续地向系统发送“用户仍在活动”的信号。2.2 与系统节能设置的博弈这里有一个重要的细节工具模拟的是用户活动而非直接修改系统电源设置。这意味着它的效果受到系统“节能”偏好设置中“防止电脑在显示器关闭时自动进入睡眠”和“唤醒以供网络访问”等选项的制约。如果用户设置了“此时间段后关闭显示器”那么即使鼠标在动显示器到时间仍然会关闭但系统不会进入深度睡眠CPU 等仍可运行。如果设置了“此时间段后使电脑进入睡眠”那么当这个时间远长于工具的活动间隔时睡眠仍可能被触发。因此这个工具的最佳实践场景是在系统节能设置允许的“活动窗口期”内通过模拟输入来不断重置这个空闲计时器从而阻止睡眠/屏保在预期时间点之前发生。它无法超越系统硬性的电源管理策略但可以巧妙地利用规则内的空间。2.3 权限问题辅助功能权限从 macOS 10.14 (Mojave) 开始出于安全考虑应用程序想要模拟鼠标、键盘事件或读取其他应用窗口信息都需要用户明确授予辅助功能 (Accessibility)权限。这对于move-mouse-macOS这样的工具来说是必须跨过的一道坎。当你第一次运行编译后的二进制文件时系统可能会弹出提示框要求你进入“系统偏好设置 安全性与隐私 隐私 辅助功能”中手动勾选你的终端如 Terminal.app 或 iTerm2或者该二进制文件本身。如果没有正确授权程序将无法创建和投递鼠标事件运行后不会有任何效果通常也不会有错误提示静默失败。注意在较新版本的 macOS如 Ventura, Sonoma上对于通过sudo以 root 权限运行的程序权限管理更为严格。有时即使为终端授权了通过sudo运行的子进程环境也可能无法继承该权限。最稳妥的方式是先将工具编译为可执行文件然后直接运行该文件非sudo在弹窗中为其本身授权。3. 从源码到可执行文件编译与部署详解ansh-info/move-mouse-macOS项目通常以源代码形式提供。我们需要将其编译为可以在终端中直接运行的二进制文件。这个过程本身也是理解一个 Swift 命令行项目的好机会。3.1 环境准备与源码获取首先确保你的 macOS 系统安装了Xcode Command Line Tools。这是编译 Swift 项目的基础。可以在终端中通过以下命令安装或检查xcode-select --install如果已经安装该命令会提示“已经安装”。接下来获取项目源代码。通常使用 Git 克隆git clone https://github.com/ansh-info/move-mouse-macOS.git cd move-mouse-macOS进入项目目录后你会看到主要的源代码文件如main.swift、配置文件Package.swift和 README。3.2 使用 Swift Package Manager (SPM) 进行编译该项目使用 Swift Package Manager 进行依赖管理和构建。这是苹果官方的包管理工具无需 Xcode 项目文件也能编译。编译命令非常简单swift build -c release这条命令的含义是swift build: 调用 SPM 的构建指令。-c release: 指定构建配置为release。与debug模式相比release模式会进行编译器优化移除调试符号生成体积更小、运行速度更快的可执行文件非常适合用于生产环境。编译过程会下载并解析项目依赖虽然这个工具可能没有外部依赖然后进行编译。完成后可执行文件位于.build/release/目录下名字通常与Package.swift中定义的name一致例如move-mouse-macOS。3.3 安装与系统集成得到可执行文件后你可以选择几种使用方式直接运行每次使用时切换到该目录执行./.build/release/move-mouse-macOS。这种方式最直接但不够方便。移动到系统路径为了能在任何终端窗口直接通过命令名调用可以将编译好的二进制文件复制到系统路径下例如/usr/local/bin/需要管理员权限sudo cp .build/release/move-mouse-macOS /usr/local/bin/之后你就可以在任意终端直接输入move-mouse-macOS来启动它了。创建别名 (Alias)如果你不想污染系统路径可以在你的 shell 配置文件如~/.zshrc或~/.bash_profile中添加一个别名alias keepawake/path/to/your/move-mouse-macOS/.build/release/move-mouse-macOS然后执行source ~/.zshrc使配置生效之后就可以用keepawake命令来启动了。3.4 首次运行的权限配置如前所述首次运行时会遇到辅助功能权限问题。假设你已经将工具安装到了/usr/local/bin/move-mouse-macOS。首先尝试直接运行一次move-mouse-macOS此时程序开始运行可能会在后台持续执行但系统可能不会立即弹窗。你可以尝试触发一下需要辅助功能权限的操作比如在程序中设计一个立即移动鼠标的命令或者直接去“系统偏好设置”中查看。打开系统偏好设置 安全性与隐私 隐私 辅助功能。点击左下角的锁图标解锁。检查列表里是否有Terminal、iTerm或者move-mouse-macOS。如果都没有你可能需要点击号然后通过“应用程序”文件夹找到你的终端应用或者通过“访达”前往/usr/local/bin选择move-mouse-macOS二进制文件注意/usr/local/bin是隐藏目录在访达中按CmdShiftG输入路径前往。勾选对应的项目。关闭窗口务必完全退出你的终端应用Quit Terminal然后重新打开一个新的终端窗口。再次运行move-mouse-macOS此时模拟鼠标移动的功能应该生效了。你可以通过将系统“节能”设置中的“此时间段后使显示器进入睡眠”设为1分钟来快速测试效果。实操心得权限问题是新手使用此类工具时最常见的障碍。如果按照上述步骤操作后仍然无效可以尝试以下排查方法检查是否有多余的终端进程在后台确保完全退出。尝试将二进制文件复制到用户目录下如~/bin/并为其授权避免/usr/local/bin的路径权限问题。运行tccutil reset Accessibility com.apple.Terminal将com.apple.Terminal替换为你的终端应用的 Bundle Identifier来重置终端的辅助功能权限然后重新授权。注意此命令会重置该应用的所有隐私权限需谨慎使用。4. 工具使用模式与参数解析一个成熟的命令行工具应该提供灵活的使用方式。基础的move-mouse-macOS可能只提供简单的持续运行模式但我们可以基于其原理探讨和实现更丰富的使用模式。通常这类工具会支持以下一种或多种模式4.1 后台守护模式默认这是最常用的模式。工具启动后作为一个守护进程在后台持续运行按照固定的时间间隔例如每分钟模拟一次鼠标移动直到你手动终止它。# 在后台启动守护进程 move-mouse-macOS # 或者不挂起直接在前台运行会阻塞当前终端 # move-mouse-macOS # 查看后台进程 jobs -l # 将后台进程拉到前台 fg %1 # 终止进程在前台运行时按 CtrlC在后台时用 kill 命令 kill %1在这种模式下工具通常需要处理信号如 SIGINT, SIGTERM以便在用户中断时能优雅退出。4.2 单次执行模式有时我们只需要暂时“点”一下系统比如在开始一个长任务前手动触发一次重置空闲计时器。工具可以提供一个参数如-s或--single来支持单次移动。# 执行一次鼠标移动然后程序退出 move-mouse-macOS --single这个功能对于脚本集成非常有用。你可以写一个 cron 任务或 launchd 定时任务每隔一段时间如50分钟执行一次该命令而不是让一个进程常驻内存。4.3 间隔时间与像素偏移量定制固定的间隔如60秒和固定的偏移量如1像素可能不适合所有场景。高级的工具应该允许用户自定义-i或--interval: 指定模拟移动的时间间隔单位秒。例如-i 30表示每30秒移动一次。-p或--pixel: 指定每次移动的像素偏移量。例如-p 5表示每次在水平和垂直方向各移动5像素或随机方向。设置一个微小的、肉眼难以察觉的偏移量是关键避免干扰真正的鼠标操作。# 每45秒移动一次每次偏移2个像素 move-mouse-macOS --interval 45 --pixel 24.4 运行时长限制我们可能只想让工具工作一段时间比如在预计2小时的下载期间保持唤醒之后自动停止。可以增加-d或--duration参数。# 运行2小时7200秒后自动退出 move-mouse-macOS --duration 7200实现这个功能可以在主循环中增加一个总运行时间的计时器到达设定时间后跳出循环并退出程序。4.5 交互模式与状态提示对于前台运行的模式提供一些基本的交互和状态提示能提升用户体验。例如启动时打印 “Keep-awake started. Interval: 60s. Press ‘q’ to quit.”每次模拟移动时在终端输出一个简单的日志如时间戳和动作可以通过-v(verbose) 参数控制。监听键盘输入例如按q键退出。# 以详细模式运行打印每次活动日志 move-mouse-macOS --verbose5. 高级应用与系统服务集成让工具在后台默默运行是最简单的用法但将其与 macOS 的系统服务机制集成可以实现开机自启、按需唤醒等更强大的自动化功能。5.1 使用 LaunchDaemon 实现系统级守护LaunchDaemon是 macOS 用于管理系统后台服务守护进程的框架。通过创建一个.plist配置文件我们可以让move-mouse-macOS在系统启动时自动以 root 权限运行或者按计划运行。创建 plist 文件在/Library/LaunchDaemons/目录下创建一个文件例如com.user.move-mouse.plist。?xml version1.0 encodingUTF-8? !DOCTYPE plist PUBLIC -//Apple//DTD PLIST 1.0//EN http://www.apple.com/DTDs/PropertyList-1.0.dtd plist version1.0 dict keyLabel/key stringcom.user.move-mouse/string keyProgramArguments/key array string/usr/local/bin/move-mouse-macOS/string string--interval/string string55/string /array keyRunAtLoad/key true/ keyKeepAlive/key true/ keyStandardOutPath/key string/tmp/move-mouse.log/string keyStandardErrorPath/key string/tmp/move-mouse.err/string /dict /plistLabel: 服务的唯一标识符。ProgramArguments: 启动命令和参数数组。第一项必须是可执行文件的绝对路径。RunAtLoad: 设为true表示加载该 daemon 时即系统启动时就运行。KeepAlive: 设为true表示如果进程意外退出launchd 会重新启动它。StandardOutPath/StandardErrorPath: 指定标准输出和错误输出的日志文件路径便于调试。加载并启动服务# 修改文件权限 sudo chown root:wheel /Library/LaunchDaemons/com.user.move-mouse.plist # 加载服务 sudo launchctl load /Library/LaunchDaemons/com.user.move-mouse.plist # 立即启动服务如果RunAtLoad为true加载时已启动 sudo launchctl start com.user.move-mouse # 查看服务状态 sudo launchctl list | grep com.user.move-mouse # 停止服务 sudo launchctl stop com.user.move-mouse # 卸载服务 sudo launchctl unload /Library/LaunchDaemons/com.user.move-mouse.plist重要警告使用 LaunchDaemon 以 root 权限运行会带来严重的辅助功能权限问题。系统级的守护进程在获取辅助功能权限上非常困难且存在安全风险。通常模拟用户输入的工具不适合也不推荐作为系统级守护进程运行。上述示例更多是展示 launchd 的用法实际应用中应优先考虑用户级的 LaunchAgent。5.2 使用 LaunchAgent 实现用户级自启LaunchAgent与LaunchDaemon类似但它在用户登录后运行以当前用户的权限执行。这完美地解决了辅助功能权限的问题因为 Agent 运行在用户上下文中可以像普通应用一样请求和获得权限。创建 plist 文件在~/Library/LaunchAgents/目录下创建例如com.user.move-mouse.agent.plist。内容与上述类似但去掉了可能需要 root 权限的配置。?xml version1.0 encodingUTF-8? !DOCTYPE plist PUBLIC -//Apple//DTD PLIST 1.0//EN http://www.apple.com/DTDs/PropertyList-1.0.dtd plist version1.0 dict keyLabel/key stringcom.user.move-mouse.agent/string keyProgramArguments/key array string/usr/local/bin/move-mouse-macOS/string string--interval/string string300/string !-- 每5分钟一次减少不必要的活动 -- /array keyRunAtLoad/key true/ keyKeepAlive/key false/ !-- 不需要常驻我们可能希望它只在特定场景运行 -- keyStandardOutPath/key string/tmp/move-mouse-agent.log/string keyStandardErrorPath/key string/tmp/move-mouse-agent.err/string /dict /plist加载 Agent(无需 sudo)launchctl load ~/Library/LaunchAgents/com.user.move-mouse.agent.plist launchctl start com.user.move-mouse.agent使用 LaunchAgent 是更安全、更合理的集成方式。你可以结合脚本实现更复杂的逻辑例如只在工作日的特定时间段启动这个 Agent。5.3 与自动化工具结合Hammerspoon, Keyboard Maestro对于追求极致自动化的用户可以将move-mouse-macOS的调用集成到更强大的自动化工具中。Hammerspoon: 一个用 Lua 脚本桥接系统 API 的自动化工具。你可以写一个 Lua 脚本监听网络状态、应用焦点等事件动态地启动或停止move-mouse-macOS进程。-- 示例当检测到特定Wi-Fi网络时启动保活工具 local wifiWatcher hs.wifi.watcher.new(function() local currentNetwork hs.wifi.currentNetwork() if currentNetwork “MyOfficeWiFi” then hs.execute(“/usr/local/bin/move-mouse-macOS ”) else hs.execute(“pkill -f move-mouse-macOS”) end end) wifiWatcher:start()Keyboard Maestro: 一个图形化的自动化工具。你可以创建一个宏当系统空闲时间接近阈值时通过检测鼠标键盘事件触发执行move-mouse-macOS --single命令实现“按需保活”更加节能和智能。6. 常见问题排查与优化实践在实际使用和改造move-mouse-macOS这类工具的过程中我遇到了不少典型问题也总结出一些优化技巧。6.1 问题排查清单问题现象可能原因排查步骤与解决方案程序运行后无任何效果系统依然休眠。1. 辅助功能权限未授予。2. 程序逻辑错误事件未成功创建或投递。3. 系统节能设置中“使电脑进入睡眠”时间过短工具间隔过长。1. 检查“安全性与隐私 辅助功能”中是否正确授权终端或二进制文件。完全退出终端重试。2. 为程序添加详细日志print调试确认CGEventPost是否被调用。编译时确保是release模式。3. 将工具运行间隔如-i 30设置为小于系统“睡眠”时间的一半。程序启动后鼠标指针在屏幕上乱跳或轻微抖动。像素偏移量 (--pixel) 设置过大或移动逻辑有问题如未取当前鼠标位置。1. 将--pixel参数设为 1 或 2。2. 检查代码确保是获取当前鼠标位置 (CGEventGetLocation) 后在其基础上进行微小的增量变化而不是设置绝对坐标。通过sudo运行时报错或无效。sudo环境下的辅助功能权限问题。程序可能运行在另一个安全上下文中。避免使用sudo运行此类工具。如果必须尝试先为/usr/bin/osascript(AppleScript 解释器) 授权然后通过 AppleScript 调用工具但这非常复杂且不稳定。首选用户级运行。编译失败提示 Swift 版本不兼容。项目使用的 Swift 语言版本高于或低于你本地安装的 Swift 工具链版本。1. 检查项目Package.swift中声明的 Swift 工具版本 (swift-tools-version)。2. 使用swift --version查看本地版本。3. 更新 Xcode Command Line Tools (xcode-select --install) 或通过 swift.org 安装匹配版本的 Swift。LaunchAgent/LaunchDaemon 加载成功但工具未运行。1. plist 文件语法错误。2. 可执行文件路径错误或无权执行。3.StandardErrorPath指定的日志文件无权写入。1. 使用plutil -lint /path/to/your.plist检查 plist 语法。2. 检查ProgramArguments中的路径确保二进制文件存在且有执行权限 (chmod x)。3. 查看StandardErrorPath指定的.err日志文件获取错误信息。确保日志目录存在且可写。6.2 性能与资源优化一个设计良好的保活工具应该是“隐形”的几乎不消耗系统资源。选择合适的时间间隔默认的 60 秒间隔对于大多数情况是安全的。但你可以根据系统“显示器关闭”和“电脑睡眠”的时间来调整。例如如果设置显示器 5 分钟后关闭那么间隔设置为 4 分钟240秒可能就足够了。更长的间隔意味着更少的 CPU 唤醒和事件处理。使用-i 240。最小化像素移动将像素偏移量设置为 1。这足以被系统事件捕捉器识别为用户活动同时又几乎不可能被肉眼察觉不会干扰任何真正的屏幕操作或全屏应用/游戏。避免繁忙循环 (Busy Loop)在工具的主循环中使用Thread.sleep(forTimeInterval:)或DispatchQueue.main.asyncAfter来进行延时而不是进行空转的while循环。这可以显著降低 CPU 占用率。一个设计糟糕的、空转的循环可能导致一个核心的 CPU 使用率持续在 100%。考虑使用IOKit电源断言对于更专业的需求可以研究IOKit/pwr_mgt中的IOPMAssertionCreateWithNameAPI。它可以创建一个“电源断言”明确告知系统当前有任务需要防止睡眠例如kIOPMAssertionTypeNoDisplaySleep防止显示器睡眠kIOPMAssertionTypePreventUserIdleDisplaySleep防止用户空闲导致的显示睡眠。这比模拟鼠标事件更直接、更高效且不需要辅助功能权限。但它的作用范围更偏向于“防止睡眠”而非“模拟活动”且需要处理断言的生命周期。你可以将两者结合用电源断言防止深度睡眠用鼠标移动防止屏保和锁定。6.3 安全与隐私考量任何模拟用户输入的程序都需要谨慎对待其安全性和隐私性。源码审查从 GitHub 等平台下载开源工具时花几分钟浏览一下main.swift的核心逻辑。确保它只做了“移动鼠标”这一件事没有隐藏的网络请求、文件操作或其他可疑行为。最小权限原则只为必要的终端或二进制文件授予辅助功能权限。不要图方便而给整个“终端”应用永久授权尽管很常见而是可以尝试先为具体的二进制文件授权。定期检查“安全性与隐私”中已授权的应用列表移除不再需要的项目。避免以高权限运行坚决不要将此类工具配置为以 root 权限长期运行如通过 LaunchDaemon。这极大地增加了安全风险。用户级的 LaunchAgent 是更安全的选择。使用沙盒如果可能对于自己开发或分发的工具考虑使用 App Sandbox。虽然沙盒应用获取辅助功能权限需要用户手动在系统偏好设置中勾选且模拟输入事件在沙盒内受限但这是一种更现代、更安全的应用分发模式。对于个人使用的命令行工具这一点不是必须的但值得了解。7. 扩展思路超越简单的鼠标移动原版move-mouse-macOS项目提供了一个坚实可靠的基础。基于此我们可以扩展出更多实用的功能使其从一个单一工具进化成一个功能丰富的“系统活动管家”。模拟多种输入事件除了鼠标移动还可以模拟轻微的键盘事件如按下并释放一个不常用的功能键F15。这能进一步确保系统识别为活动。组合使用鼠标移动和键盘事件可以创建更“自然”的活动模式。条件触发与智能暂停网络活动检测在下载或上传大文件时保持唤醒传输完成后自动暂停。可以通过检查网络接口的流量数据来实现。CPU 负载检测当系统正在进行高强度计算如渲染、编译时保持唤醒空闲时暂停。特定应用前台检测仅当某个特定应用如终端、Docker Desktop、视频会议软件处于前台或运行时才启用保活。这可以通过NSWorkspace的 API 监听应用激活状态来实现。提供图形界面 (GUI) 或状态栏菜单对于不习惯命令行的用户可以为其包裹一个简单的 macOS 状态栏 (Menu Bar) 应用。使用 SwiftUI 或 AppKit 快速构建一个菜单提供“开始/停止”、“设置间隔”、“显示剩余时间”等控件并显示当前状态图标。这能极大提升工具的易用性和可管理性。与焦点模式 (Focus Mode) 集成在 macOS 的“专注模式”下系统通知和某些行为会改变。可以让工具在“工作”专注模式开启时自动运行在“个人”或“睡眠”模式开启时自动停止。实现“咖啡模式”这是一个经典功能启动后工具运行一个固定的时长例如 30 分钟然后自动停止并播放一个提示音。这非常适合需要短暂离开但又不想永久禁用睡眠的场景。通过以上这些扩展一个简单的鼠标移动脚本就能演变成为一个高度可定制、智能化的系统辅助工具。这正体现了开源项目的魅力从一个具体的需求点出发通过社区和个人的智慧不断迭代和丰富最终解决更广泛、更复杂的问题。ansh-info/move-mouse-macOS提供了一个优秀的起点和清晰的核心实现剩下的就交给使用者的想象力和具体的场景需求了。
macOS防休眠工具：模拟鼠标移动保持系统活跃的原理与实践
发布时间：2026/7/26 1:58:49
1. 项目概述一个解决 macOS 用户“痛点”的小工具如果你是一名 macOS 用户并且经常需要长时间离开电脑但又不想让系统进入睡眠状态或触发屏幕保护程序那么你很可能遇到过这样的困扰正在进行的下载、渲染、编译或者远程连接因为系统误判你“已离开”而中断。我最初注意到ansh-info/move-mouse-macOS这个项目就是因为它精准地瞄准了这个看似微小、实则恼人的需求。这并非一个复杂的系统级应用而是一个用 Swift 编写的、功能极其聚焦的命令行工具——它的核心使命只有一个自动、可控地模拟鼠标移动从而“欺骗”系统使其保持活跃状态。在 macOS 的开发或日常使用场景中系统基于用户活动键盘、鼠标、触控板输入来判断是否空闲。一旦超过设定的时间便会启动屏幕保护、降低亮度甚至进入睡眠。虽然系统偏好设置中提供了相关选项但很多时候我们需要更灵活、更临时的控制。比如在服务器端执行一个长达数小时的脚本时你希望 Mac 保持唤醒但又不希望修改全局的节能设置或者在进行视频会议共享屏幕时需要防止屏幕变暗。手动时不时晃动鼠标显然不是优雅的解决方案。move-mouse-macOS的出现提供了一种轻量级、可编程的自动化手段。这个项目本质上是一个“防休眠”或“保活”工具。它通过编程方式向系统发送模拟的鼠标移动事件让系统认为用户仍在操作从而阻止其进入休眠或屏保状态。对于开发者、设计师、视频工作者或者任何需要 Mac 长时间执行任务而不被中断的用户来说这是一个实用价值很高的小工具。它的代码仓库结构清晰采用 Swift 编写天然与 macOS 系统集成良好避免了跨平台工具可能存在的兼容性问题。接下来我将深入拆解这个工具的设计思路、核心实现、使用方法以及我本人在实际部署和扩展过程中积累的一些经验。2. 核心原理与系统交互机制要理解move-mouse-macOS如何工作首先需要了解 macOS 是如何处理用户输入和系统电源管理的。macOS 的核心框架之一是IOKit和Quartz Event Services。我们的鼠标、键盘等输入设备产生的信号最终会通过这些框架转化为系统能够理解的CGEventCore Graphics Event。系统电源管理守护进程powerd则会监听这些事件的发生频率。当在一段时间内没有检测到新的 CGEvent它就会按照预设的策略逐步执行降低屏幕亮度、启动屏保、进入睡眠等操作。2.1 模拟输入事件的核心 APImove-mouse-macOS工具的核心在于调用Quartz Event Services中的CGEventCreateMouseEvent和CGEventPost这两个关键函数。CGEventCreateMouseEvent: 这个函数用于创建一个新的鼠标事件。你需要告诉它事件类型是鼠标移动kCGEventMouseMoved、左键按下kCGEventLeftMouseDown还是其他。事件发生的位置以屏幕坐标CGFloat表示。鼠标按钮状态对于移动事件通常传入kCGMouseButtonLeft或kCGMouseButtonCenter等但实际移动事件不依赖按钮状态。CGEventPost: 创建事件后需要将其“投递”到系统的事件流中。这里通常使用CGEventPost(.cghidEventTap, event)。cghidEventTap表示将事件投递到系统底层的人机接口设备HID事件流这模拟了真实硬件产生的输入因此能够有效地被电源管理系统识别。通过周期性地例如每隔 55 秒创建一个将鼠标移动到当前位置附近比如偏移 1 个像素的kCGEventMouseMoved事件并投递工具就能持续地向系统发送“用户仍在活动”的信号。2.2 与系统节能设置的博弈这里有一个重要的细节工具模拟的是用户活动而非直接修改系统电源设置。这意味着它的效果受到系统“节能”偏好设置中“防止电脑在显示器关闭时自动进入睡眠”和“唤醒以供网络访问”等选项的制约。如果用户设置了“此时间段后关闭显示器”那么即使鼠标在动显示器到时间仍然会关闭但系统不会进入深度睡眠CPU 等仍可运行。如果设置了“此时间段后使电脑进入睡眠”那么当这个时间远长于工具的活动间隔时睡眠仍可能被触发。因此这个工具的最佳实践场景是在系统节能设置允许的“活动窗口期”内通过模拟输入来不断重置这个空闲计时器从而阻止睡眠/屏保在预期时间点之前发生。它无法超越系统硬性的电源管理策略但可以巧妙地利用规则内的空间。2.3 权限问题辅助功能权限从 macOS 10.14 (Mojave) 开始出于安全考虑应用程序想要模拟鼠标、键盘事件或读取其他应用窗口信息都需要用户明确授予辅助功能 (Accessibility)权限。这对于move-mouse-macOS这样的工具来说是必须跨过的一道坎。当你第一次运行编译后的二进制文件时系统可能会弹出提示框要求你进入“系统偏好设置 安全性与隐私 隐私 辅助功能”中手动勾选你的终端如 Terminal.app 或 iTerm2或者该二进制文件本身。如果没有正确授权程序将无法创建和投递鼠标事件运行后不会有任何效果通常也不会有错误提示静默失败。注意在较新版本的 macOS如 Ventura, Sonoma上对于通过sudo以 root 权限运行的程序权限管理更为严格。有时即使为终端授权了通过sudo运行的子进程环境也可能无法继承该权限。最稳妥的方式是先将工具编译为可执行文件然后直接运行该文件非sudo在弹窗中为其本身授权。3. 从源码到可执行文件编译与部署详解ansh-info/move-mouse-macOS项目通常以源代码形式提供。我们需要将其编译为可以在终端中直接运行的二进制文件。这个过程本身也是理解一个 Swift 命令行项目的好机会。3.1 环境准备与源码获取首先确保你的 macOS 系统安装了Xcode Command Line Tools。这是编译 Swift 项目的基础。可以在终端中通过以下命令安装或检查xcode-select --install如果已经安装该命令会提示“已经安装”。接下来获取项目源代码。通常使用 Git 克隆git clone https://github.com/ansh-info/move-mouse-macOS.git cd move-mouse-macOS进入项目目录后你会看到主要的源代码文件如main.swift、配置文件Package.swift和 README。3.2 使用 Swift Package Manager (SPM) 进行编译该项目使用 Swift Package Manager 进行依赖管理和构建。这是苹果官方的包管理工具无需 Xcode 项目文件也能编译。编译命令非常简单swift build -c release这条命令的含义是swift build: 调用 SPM 的构建指令。-c release: 指定构建配置为release。与debug模式相比release模式会进行编译器优化移除调试符号生成体积更小、运行速度更快的可执行文件非常适合用于生产环境。编译过程会下载并解析项目依赖虽然这个工具可能没有外部依赖然后进行编译。完成后可执行文件位于.build/release/目录下名字通常与Package.swift中定义的name一致例如move-mouse-macOS。3.3 安装与系统集成得到可执行文件后你可以选择几种使用方式直接运行每次使用时切换到该目录执行./.build/release/move-mouse-macOS。这种方式最直接但不够方便。移动到系统路径为了能在任何终端窗口直接通过命令名调用可以将编译好的二进制文件复制到系统路径下例如/usr/local/bin/需要管理员权限sudo cp .build/release/move-mouse-macOS /usr/local/bin/之后你就可以在任意终端直接输入move-mouse-macOS来启动它了。创建别名 (Alias)如果你不想污染系统路径可以在你的 shell 配置文件如~/.zshrc或~/.bash_profile中添加一个别名alias keepawake/path/to/your/move-mouse-macOS/.build/release/move-mouse-macOS然后执行source ~/.zshrc使配置生效之后就可以用keepawake命令来启动了。3.4 首次运行的权限配置如前所述首次运行时会遇到辅助功能权限问题。假设你已经将工具安装到了/usr/local/bin/move-mouse-macOS。首先尝试直接运行一次move-mouse-macOS此时程序开始运行可能会在后台持续执行但系统可能不会立即弹窗。你可以尝试触发一下需要辅助功能权限的操作比如在程序中设计一个立即移动鼠标的命令或者直接去“系统偏好设置”中查看。打开系统偏好设置 安全性与隐私 隐私 辅助功能。点击左下角的锁图标解锁。检查列表里是否有Terminal、iTerm或者move-mouse-macOS。如果都没有你可能需要点击号然后通过“应用程序”文件夹找到你的终端应用或者通过“访达”前往/usr/local/bin选择move-mouse-macOS二进制文件注意/usr/local/bin是隐藏目录在访达中按CmdShiftG输入路径前往。勾选对应的项目。关闭窗口务必完全退出你的终端应用Quit Terminal然后重新打开一个新的终端窗口。再次运行move-mouse-macOS此时模拟鼠标移动的功能应该生效了。你可以通过将系统“节能”设置中的“此时间段后使显示器进入睡眠”设为1分钟来快速测试效果。实操心得权限问题是新手使用此类工具时最常见的障碍。如果按照上述步骤操作后仍然无效可以尝试以下排查方法检查是否有多余的终端进程在后台确保完全退出。尝试将二进制文件复制到用户目录下如~/bin/并为其授权避免/usr/local/bin的路径权限问题。运行tccutil reset Accessibility com.apple.Terminal将com.apple.Terminal替换为你的终端应用的 Bundle Identifier来重置终端的辅助功能权限然后重新授权。注意此命令会重置该应用的所有隐私权限需谨慎使用。4. 工具使用模式与参数解析一个成熟的命令行工具应该提供灵活的使用方式。基础的move-mouse-macOS可能只提供简单的持续运行模式但我们可以基于其原理探讨和实现更丰富的使用模式。通常这类工具会支持以下一种或多种模式4.1 后台守护模式默认这是最常用的模式。工具启动后作为一个守护进程在后台持续运行按照固定的时间间隔例如每分钟模拟一次鼠标移动直到你手动终止它。# 在后台启动守护进程 move-mouse-macOS # 或者不挂起直接在前台运行会阻塞当前终端 # move-mouse-macOS # 查看后台进程 jobs -l # 将后台进程拉到前台 fg %1 # 终止进程在前台运行时按 CtrlC在后台时用 kill 命令 kill %1在这种模式下工具通常需要处理信号如 SIGINT, SIGTERM以便在用户中断时能优雅退出。4.2 单次执行模式有时我们只需要暂时“点”一下系统比如在开始一个长任务前手动触发一次重置空闲计时器。工具可以提供一个参数如-s或--single来支持单次移动。# 执行一次鼠标移动然后程序退出 move-mouse-macOS --single这个功能对于脚本集成非常有用。你可以写一个 cron 任务或 launchd 定时任务每隔一段时间如50分钟执行一次该命令而不是让一个进程常驻内存。4.3 间隔时间与像素偏移量定制固定的间隔如60秒和固定的偏移量如1像素可能不适合所有场景。高级的工具应该允许用户自定义-i或--interval: 指定模拟移动的时间间隔单位秒。例如-i 30表示每30秒移动一次。-p或--pixel: 指定每次移动的像素偏移量。例如-p 5表示每次在水平和垂直方向各移动5像素或随机方向。设置一个微小的、肉眼难以察觉的偏移量是关键避免干扰真正的鼠标操作。# 每45秒移动一次每次偏移2个像素 move-mouse-macOS --interval 45 --pixel 24.4 运行时长限制我们可能只想让工具工作一段时间比如在预计2小时的下载期间保持唤醒之后自动停止。可以增加-d或--duration参数。# 运行2小时7200秒后自动退出 move-mouse-macOS --duration 7200实现这个功能可以在主循环中增加一个总运行时间的计时器到达设定时间后跳出循环并退出程序。4.5 交互模式与状态提示对于前台运行的模式提供一些基本的交互和状态提示能提升用户体验。例如启动时打印 “Keep-awake started. Interval: 60s. Press ‘q’ to quit.”每次模拟移动时在终端输出一个简单的日志如时间戳和动作可以通过-v(verbose) 参数控制。监听键盘输入例如按q键退出。# 以详细模式运行打印每次活动日志 move-mouse-macOS --verbose5. 高级应用与系统服务集成让工具在后台默默运行是最简单的用法但将其与 macOS 的系统服务机制集成可以实现开机自启、按需唤醒等更强大的自动化功能。5.1 使用 LaunchDaemon 实现系统级守护LaunchDaemon是 macOS 用于管理系统后台服务守护进程的框架。通过创建一个.plist配置文件我们可以让move-mouse-macOS在系统启动时自动以 root 权限运行或者按计划运行。创建 plist 文件在/Library/LaunchDaemons/目录下创建一个文件例如com.user.move-mouse.plist。?xml version1.0 encodingUTF-8? !DOCTYPE plist PUBLIC -//Apple//DTD PLIST 1.0//EN http://www.apple.com/DTDs/PropertyList-1.0.dtd plist version1.0 dict keyLabel/key stringcom.user.move-mouse/string keyProgramArguments/key array string/usr/local/bin/move-mouse-macOS/string string--interval/string string55/string /array keyRunAtLoad/key true/ keyKeepAlive/key true/ keyStandardOutPath/key string/tmp/move-mouse.log/string keyStandardErrorPath/key string/tmp/move-mouse.err/string /dict /plistLabel: 服务的唯一标识符。ProgramArguments: 启动命令和参数数组。第一项必须是可执行文件的绝对路径。RunAtLoad: 设为true表示加载该 daemon 时即系统启动时就运行。KeepAlive: 设为true表示如果进程意外退出launchd 会重新启动它。StandardOutPath/StandardErrorPath: 指定标准输出和错误输出的日志文件路径便于调试。加载并启动服务# 修改文件权限 sudo chown root:wheel /Library/LaunchDaemons/com.user.move-mouse.plist # 加载服务 sudo launchctl load /Library/LaunchDaemons/com.user.move-mouse.plist # 立即启动服务如果RunAtLoad为true加载时已启动 sudo launchctl start com.user.move-mouse # 查看服务状态 sudo launchctl list | grep com.user.move-mouse # 停止服务 sudo launchctl stop com.user.move-mouse # 卸载服务 sudo launchctl unload /Library/LaunchDaemons/com.user.move-mouse.plist重要警告使用 LaunchDaemon 以 root 权限运行会带来严重的辅助功能权限问题。系统级的守护进程在获取辅助功能权限上非常困难且存在安全风险。通常模拟用户输入的工具不适合也不推荐作为系统级守护进程运行。上述示例更多是展示 launchd 的用法实际应用中应优先考虑用户级的 LaunchAgent。5.2 使用 LaunchAgent 实现用户级自启LaunchAgent与LaunchDaemon类似但它在用户登录后运行以当前用户的权限执行。这完美地解决了辅助功能权限的问题因为 Agent 运行在用户上下文中可以像普通应用一样请求和获得权限。创建 plist 文件在~/Library/LaunchAgents/目录下创建例如com.user.move-mouse.agent.plist。内容与上述类似但去掉了可能需要 root 权限的配置。?xml version1.0 encodingUTF-8? !DOCTYPE plist PUBLIC -//Apple//DTD PLIST 1.0//EN http://www.apple.com/DTDs/PropertyList-1.0.dtd plist version1.0 dict keyLabel/key stringcom.user.move-mouse.agent/string keyProgramArguments/key array string/usr/local/bin/move-mouse-macOS/string string--interval/string string300/string !-- 每5分钟一次减少不必要的活动 -- /array keyRunAtLoad/key true/ keyKeepAlive/key false/ !-- 不需要常驻我们可能希望它只在特定场景运行 -- keyStandardOutPath/key string/tmp/move-mouse-agent.log/string keyStandardErrorPath/key string/tmp/move-mouse-agent.err/string /dict /plist加载 Agent(无需 sudo)launchctl load ~/Library/LaunchAgents/com.user.move-mouse.agent.plist launchctl start com.user.move-mouse.agent使用 LaunchAgent 是更安全、更合理的集成方式。你可以结合脚本实现更复杂的逻辑例如只在工作日的特定时间段启动这个 Agent。5.3 与自动化工具结合Hammerspoon, Keyboard Maestro对于追求极致自动化的用户可以将move-mouse-macOS的调用集成到更强大的自动化工具中。Hammerspoon: 一个用 Lua 脚本桥接系统 API 的自动化工具。你可以写一个 Lua 脚本监听网络状态、应用焦点等事件动态地启动或停止move-mouse-macOS进程。-- 示例当检测到特定Wi-Fi网络时启动保活工具 local wifiWatcher hs.wifi.watcher.new(function() local currentNetwork hs.wifi.currentNetwork() if currentNetwork “MyOfficeWiFi” then hs.execute(“/usr/local/bin/move-mouse-macOS ”) else hs.execute(“pkill -f move-mouse-macOS”) end end) wifiWatcher:start()Keyboard Maestro: 一个图形化的自动化工具。你可以创建一个宏当系统空闲时间接近阈值时通过检测鼠标键盘事件触发执行move-mouse-macOS --single命令实现“按需保活”更加节能和智能。6. 常见问题排查与优化实践在实际使用和改造move-mouse-macOS这类工具的过程中我遇到了不少典型问题也总结出一些优化技巧。6.1 问题排查清单问题现象可能原因排查步骤与解决方案程序运行后无任何效果系统依然休眠。1. 辅助功能权限未授予。2. 程序逻辑错误事件未成功创建或投递。3. 系统节能设置中“使电脑进入睡眠”时间过短工具间隔过长。1. 检查“安全性与隐私 辅助功能”中是否正确授权终端或二进制文件。完全退出终端重试。2. 为程序添加详细日志print调试确认CGEventPost是否被调用。编译时确保是release模式。3. 将工具运行间隔如-i 30设置为小于系统“睡眠”时间的一半。程序启动后鼠标指针在屏幕上乱跳或轻微抖动。像素偏移量 (--pixel) 设置过大或移动逻辑有问题如未取当前鼠标位置。1. 将--pixel参数设为 1 或 2。2. 检查代码确保是获取当前鼠标位置 (CGEventGetLocation) 后在其基础上进行微小的增量变化而不是设置绝对坐标。通过sudo运行时报错或无效。sudo环境下的辅助功能权限问题。程序可能运行在另一个安全上下文中。避免使用sudo运行此类工具。如果必须尝试先为/usr/bin/osascript(AppleScript 解释器) 授权然后通过 AppleScript 调用工具但这非常复杂且不稳定。首选用户级运行。编译失败提示 Swift 版本不兼容。项目使用的 Swift 语言版本高于或低于你本地安装的 Swift 工具链版本。1. 检查项目Package.swift中声明的 Swift 工具版本 (swift-tools-version)。2. 使用swift --version查看本地版本。3. 更新 Xcode Command Line Tools (xcode-select --install) 或通过 swift.org 安装匹配版本的 Swift。LaunchAgent/LaunchDaemon 加载成功但工具未运行。1. plist 文件语法错误。2. 可执行文件路径错误或无权执行。3.StandardErrorPath指定的日志文件无权写入。1. 使用plutil -lint /path/to/your.plist检查 plist 语法。2. 检查ProgramArguments中的路径确保二进制文件存在且有执行权限 (chmod x)。3. 查看StandardErrorPath指定的.err日志文件获取错误信息。确保日志目录存在且可写。6.2 性能与资源优化一个设计良好的保活工具应该是“隐形”的几乎不消耗系统资源。选择合适的时间间隔默认的 60 秒间隔对于大多数情况是安全的。但你可以根据系统“显示器关闭”和“电脑睡眠”的时间来调整。例如如果设置显示器 5 分钟后关闭那么间隔设置为 4 分钟240秒可能就足够了。更长的间隔意味着更少的 CPU 唤醒和事件处理。使用-i 240。最小化像素移动将像素偏移量设置为 1。这足以被系统事件捕捉器识别为用户活动同时又几乎不可能被肉眼察觉不会干扰任何真正的屏幕操作或全屏应用/游戏。避免繁忙循环 (Busy Loop)在工具的主循环中使用Thread.sleep(forTimeInterval:)或DispatchQueue.main.asyncAfter来进行延时而不是进行空转的while循环。这可以显著降低 CPU 占用率。一个设计糟糕的、空转的循环可能导致一个核心的 CPU 使用率持续在 100%。考虑使用IOKit电源断言对于更专业的需求可以研究IOKit/pwr_mgt中的IOPMAssertionCreateWithNameAPI。它可以创建一个“电源断言”明确告知系统当前有任务需要防止睡眠例如kIOPMAssertionTypeNoDisplaySleep防止显示器睡眠kIOPMAssertionTypePreventUserIdleDisplaySleep防止用户空闲导致的显示睡眠。这比模拟鼠标事件更直接、更高效且不需要辅助功能权限。但它的作用范围更偏向于“防止睡眠”而非“模拟活动”且需要处理断言的生命周期。你可以将两者结合用电源断言防止深度睡眠用鼠标移动防止屏保和锁定。6.3 安全与隐私考量任何模拟用户输入的程序都需要谨慎对待其安全性和隐私性。源码审查从 GitHub 等平台下载开源工具时花几分钟浏览一下main.swift的核心逻辑。确保它只做了“移动鼠标”这一件事没有隐藏的网络请求、文件操作或其他可疑行为。最小权限原则只为必要的终端或二进制文件授予辅助功能权限。不要图方便而给整个“终端”应用永久授权尽管很常见而是可以尝试先为具体的二进制文件授权。定期检查“安全性与隐私”中已授权的应用列表移除不再需要的项目。避免以高权限运行坚决不要将此类工具配置为以 root 权限长期运行如通过 LaunchDaemon。这极大地增加了安全风险。用户级的 LaunchAgent 是更安全的选择。使用沙盒如果可能对于自己开发或分发的工具考虑使用 App Sandbox。虽然沙盒应用获取辅助功能权限需要用户手动在系统偏好设置中勾选且模拟输入事件在沙盒内受限但这是一种更现代、更安全的应用分发模式。对于个人使用的命令行工具这一点不是必须的但值得了解。7. 扩展思路超越简单的鼠标移动原版move-mouse-macOS项目提供了一个坚实可靠的基础。基于此我们可以扩展出更多实用的功能使其从一个单一工具进化成一个功能丰富的“系统活动管家”。模拟多种输入事件除了鼠标移动还可以模拟轻微的键盘事件如按下并释放一个不常用的功能键F15。这能进一步确保系统识别为活动。组合使用鼠标移动和键盘事件可以创建更“自然”的活动模式。条件触发与智能暂停网络活动检测在下载或上传大文件时保持唤醒传输完成后自动暂停。可以通过检查网络接口的流量数据来实现。CPU 负载检测当系统正在进行高强度计算如渲染、编译时保持唤醒空闲时暂停。特定应用前台检测仅当某个特定应用如终端、Docker Desktop、视频会议软件处于前台或运行时才启用保活。这可以通过NSWorkspace的 API 监听应用激活状态来实现。提供图形界面 (GUI) 或状态栏菜单对于不习惯命令行的用户可以为其包裹一个简单的 macOS 状态栏 (Menu Bar) 应用。使用 SwiftUI 或 AppKit 快速构建一个菜单提供“开始/停止”、“设置间隔”、“显示剩余时间”等控件并显示当前状态图标。这能极大提升工具的易用性和可管理性。与焦点模式 (Focus Mode) 集成在 macOS 的“专注模式”下系统通知和某些行为会改变。可以让工具在“工作”专注模式开启时自动运行在“个人”或“睡眠”模式开启时自动停止。实现“咖啡模式”这是一个经典功能启动后工具运行一个固定的时长例如 30 分钟然后自动停止并播放一个提示音。这非常适合需要短暂离开但又不想永久禁用睡眠的场景。通过以上这些扩展一个简单的鼠标移动脚本就能演变成为一个高度可定制、智能化的系统辅助工具。这正体现了开源项目的魅力从一个具体的需求点出发通过社区和个人的智慧不断迭代和丰富最终解决更广泛、更复杂的问题。ansh-info/move-mouse-macOS提供了一个优秀的起点和清晰的核心实现剩下的就交给使用者的想象力和具体的场景需求了。
