Mac Mouse Fix：把十美元鼠标的滚轮和侧键改造成触控板级体验

【免费下载链接】mac-mouse-fixMac Mouse Fix - Make Your $10 Mouse Better Than an Apple Trackpad!项目地址: https://gitcode.com/GitHub_Trending/ma/mac-mouse-fix

Mac Mouse Fix 是一个开源 macOS 应用，专门解决第三方鼠标在 Mac 上的短板：滚轮跳动、侧键无效、无手势支持。技术定位是一个独立 Helper 进程，在系统输入链路中拦截鼠标事件并重新分发。

📋 项目速览

为什么值得关注：它把"鼠标驱动"这件事从闭源厂商手里拿回来，用一套完整的开源实现（滚轮平滑、按键捕获、手势模拟）覆盖了 Logi Options 这类商业软件的核心能力，而且滚轮和按键的行为都可以按自己的习惯重写。

🖱 它到底帮你做了什么

侧键捕获与任意动作映射

用户感知到的变化：鼠标侧键不再是"系统里点不亮的死按钮"，而是可以绑到任何系统动作。

• Helper 进程先于目标应用捕获按键事件，被映射的按键对其他应用"消失"，避免冲突
• 触发方式覆盖单击、双击、长按、组合键（如"按键 5 + 中键"）
• 动作库包括启动台、调度中心、窗口切换、智能缩放等系统级操作，还能模拟任意键盘按键

源码位置

滚轮平滑与触控板模拟

用户感知到的变化：一格一格的滚轮变成带惯性、可反向急停的连续滚动，接近 Apple Trackpad 的手感。

• 用动量曲线把离散的滚轮脉冲转成平滑增量，反向拨一格即可刹车
• 修饰键体系：水平、精确（precise）、快速（swift）、缩放（zoom）滚动各对应一个独立按键
• 配置项含 smooth 平滑档位、speed 速度档位与方向反转，都持久化在config.plist

源码位置

指针速度与加速度

用户感知到的变化：光标移动的手感可以被独立调校，不再完全交给系统默认曲线。

• 内置加速度表桥接（IOHIDAccelerationTableBridge）与灵敏度调节
• 可切换系统加速度或应用自管曲线
• 注意：目前不能在应用内直接关闭指针加速度，macOS 14 及以上需到 系统设置 → 鼠标 → 高级 中处理

点击拖拽手势：把两指轻扫搬进鼠标

用户感知到的变化：按住某个键拖拽，就能触发平时属于触控板手势的操作。

• "滚动与导航"（Scroll & Navigate）模拟两指滑动，可打开 App Exposé、Launchpad、Mission Control
• 配合第三方窗口管理工具，一个键加拖拽即可把窗口吸附到半屏、四分之一屏
• 中键拖拽在 Blender 等 3D 软件中的轨道操作也由此承接

源码位置

🚀 从零跑起来

最短可行路径，以源码方式安装为例：

1. 获取仓库：git clone https://gitcode.com/GitHub_Trending/ma/mac-mouse-fix
2. 用 Xcode 打开仓库根目录的Mouse Fix.xcodeproj，分别构建 App 和 Helper 两个 target（Helper/目录对应 Helper 应用）
3. 启动应用后授予辅助功能权限：系统设置 → 隐私与安全性 → 辅助功能，勾选 Mac Mouse Fix
4. 打开应用，打开 Enable 开关，此时 Helper 进程开始接管鼠标事件
5. 首次验证：进入 Buttons 标签页，把指针移进"+"区域按一下鼠标侧键。出现"按键 N 被 Mac Mouse Fix 捕获到，其他 app 无法再识别这个按键"的提示，说明链路已经通了

🎛 进阶玩法与配置方案

滚动行为调校。滚动参数集中存放在配置文件的 Scroll 区块，默认值如下（Shared/Config/default_config.plist为完整模板）：

Scroll: smooth: high # 平滑档位：none / low / medium / high speed: medium # 滚动速度档位 reverseDirection: true # 反转方向 trackpadSimulation: true # 触控板模拟

适合讨厌原生滚动行为、想要触控板惯性的日常办公用户。

侧键映射系统动作。Buttons 标签页为每个按键提供"点按 / 点按并拖移 / 双击 / 长按"四个槽位，每个槽位独立选动作。参考配置（截图同款布局）：

{ "中键": { "点按": "智能缩放" }, "中键": { "点按 按键5 + 点按中键": "调度中心" }, "按键4": { "点按": "启动台" }, "按键4": { "点按并拖移": "滚动与导航" } }

适合想一个侧键开启动台、一个侧键拖出 App Exposé 的效率党。

用鼠标模拟 Apple 专用键。按住 Option（⌥）可以选中亮度、音量、媒体播放这类只存在于 Apple 键盘上的按键，直接绑到鼠标按钮上。

适合无 Apple 键盘外接场景、或想把音量亮度控制移到鼠标上的用户。

⚠ 踩坑与排障

现象：点击有延迟。原因：该按键配置了 Double Click 动作，Helper 必须等待判定你是否要双击。解法：在 Buttons 标签页删掉该按键的 Double Click 动作，延迟立刻消失。

现象：某些鼠标的侧键完全不识别。原因：该鼠标走的是厂商私有协议（如 Logi Options 类驱动专属通信），不是标准 USB HID 事件，系统层拿不到。解法：确认鼠标能否以标准模式工作；私有协议按键目前无解，属于已知限制。

现象：中键粘贴、浏览器中键开链接突然失效。原因：中键被 Mac Mouse Fix 捕获后，系统默认行为被拦截。解法：删掉中键上的所有动作即可"释放"（uncapture）该键；或者把需要的默认行为显式映射回去。官方指南有完整说明。

现象：想要关闭指针加速度，应用里找不到开关。原因：该功能尚未实现在应用内。解法：macOS 14 Sonoma 及以上走 系统设置 → 鼠标 → 高级 → 关闭 Pointer acceleration；更早系统版本暂无替代。

🧭 源码导航

• Helper/Core/Buttons/：按键捕获、修饰键组合、重映射分析（RemapsAnalyzer）
• Helper/Core/Scroll/：滚动平滑、动量曲线、修饰键滚动，附带开发笔记 ScrollNotes.md
• Helper/Core/PointerSpeed/：指针速度、加速度表桥接与 Experiments 目录里的调参实验
• Shared/Config/：配置读写、版本号迁移（configVersion）与default_config.plist模板
• App/UI/Main/Tabs/：设置界面各标签页（按键、滚动、通用、关于）
• Shared/MessagePort/：App 与 Helper 进程间的本地端口通信

🎯 结语

Mac Mouse Fix 的价值在于用一套开源实现补齐了 macOS 鼠标生态的空白：滚轮平滑、侧键映射、触控板手势三件事，第一次可以在不装闭源厂商驱动的前提下全部自定义。想深入的话，克隆仓库编译最新版本是最直接的路径；遇到识别或行为问题，项目 issue 区和 Support/Guides/ 里的捕获指南是最好的排查入口。

核心关键词：macOS 鼠标增强、Mac Mouse Fix 按键映射、开源鼠标驱动

长尾关键词：macOS 侧键配置、滚轮平滑滚动优化、鼠标手势自定义、第三方鼠标兼容 macOS、鼠标替代触控板方案

【免费下载链接】mac-mouse-fixMac Mouse Fix - Make Your $10 Mouse Better Than an Apple Trackpad!项目地址: https://gitcode.com/GitHub_Trending/ma/mac-mouse-fix