Mac Mouse Fix：免费搞定 macOS 侧键映射与平滑滚动的 3 分钟完整方案
【免费下载链接】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 鼠标优化工具：它在系统层面拦截鼠标事件，支持macOS 侧键映射与鼠标按键自定义，并把手感生硬的原始滚轮替换为带惯性的平滑滚动。
macOS 鼠标支持的原生短板
macOS 对第三方鼠标有三个明显的原生短板：侧键没有系统默认动作、滚轮是一格一格的、触控板手势完全用不上。Mac Mouse Fix 用系统级事件拦截加滚动平滑引擎把这三件事补齐。下面从安装开始，把整条链路走一遍。
三分钟上手：安装到第一个按键映射
获取与安装
使用 Homebrew 的，在终端执行一行命令即可安装：
brew install mac-mouse-fix不使用 Homebrew 的，从项目 Releases 页面下载最新预编译包，双击安装即可。
权限配置
- 打开「系统设置 → 隐私与安全性 → 辅助功能」，开启 Mac Mouse Fix。
- 打开「系统设置 → 隐私与安全性 → 输入监控」，同样开启。
- 两项权限都授予后，重启应用使其生效。
映射你的第一个侧键
- 进入 Buttons 标签页，把鼠标指针移进界面中央的 "+" 区域。
- 点击要配置的侧键，例如 Button 4。
- 弹出提示确认该按键已被捕获，其他应用不再能收到这个按键。
- 在下拉列表里为它选择动作，比如 Launchpad，即刻生效。
平滑滚动与按键拦截的工作原理
平滑滚动与按键拦截是 Mac Mouse Fix 的两大核心机制，分别对应滚动生硬和侧键不可用两个问题。滚动部分由双指数平滑算法实现：滚轮转动时，它不把原始滚动量直接发给应用，而是先根据最近一段时间内的输入预测当前的滚动趋势，也就是你滚得多快、是在加速还是减速。预测出来的趋势被当作惯性延续，输入停止后光标还会继续滑行，并逐帧衰减，类似手指离开触控板玻璃后，内容还往前滑了一小段才停住。平滑强度在 Scrolling 标签页里可调，调得越高惯性越明显，整条流水线在 Helper/Core/Scroll/ 目录中。
按键拦截走的是同一条事件通道。鼠标上报的事件先经过 IOKit 层面被拦截，而不是直接交给 AppKit 分发给应用。Button 4/5 的事件在这里被捕获，再按你的配置分发到对应动作。单击、双击、点击并拖拽这些触发方式都可以绑定 Mission Control、智能缩放之类的系统功能，或任意自定义的键盘快捷键。
按工作流配置：三组实战按键方案
侧键捕获之后，剩下的事就是按自己的工作流给每个按键分配动作，下面是三组可以直接照搬的组合。
🎨 设计类软件（Figma / Photoshop）
- Button 4 单击 → 缩小画布
- Button 4 + 拖拽 → 平移画布
- 中键单击 → 智能缩放
- Button 5 单击 → 抓手工具
适用于 Figma、Photoshop 这类以画布为中心的设计工具。
💻 代码编辑器（VS Code / Xcode）
- Button 4 单击 → 切换到上一个标签页
- Button 4 双击 → 关闭当前标签页
- Button 5 单击 → Mission Control 窗口切换
- 中键单击 → 打开查找（Cmd + F）
适用于 VS Code、Xcode、IntelliJ IDEA 等代码编辑器。
📚 文档与浏览（PDF / 浏览器）
- Button 4 单击 → 上一页
- Button 5 单击 → 下一页
- Button 4 + 滚动 → 调整文档缩放
- 中键单击 → 在后台标签页打开链接
适用于 PDF 阅读器与各类浏览器。
轻量设计的底层取舍
Mac Mouse Fix 直接通过 IOKit 读取设备事件，而不是走 AppKit 的事件抽象层，这是它延迟低、占用小的根本原因。走 AppKit 的事件要经过窗口系统和多层分发，单次延迟普遍在 15–20 ms 左右，后台负载也更高。
| 指标 | 走 IOKit 直接读取 |
|---|---|
| 响应延迟 | 约 6–8 ms |
| 资源占用 | 常驻进程，占用极低 |
核心默认配置文件在 Shared/Config/default_config.plist，滚动、指针、按键映射各自独立成段，改其中一项不影响其余配置。
最常见的 3 个配置卡点
配置后不生效，绝大多数情况卡在这三个点上，按顺序排查。
权限未授予导致映射不生效
✅ 确认「系统设置 → 隐私与安全性 → 辅助功能」里 Mac Mouse Fix 已开启。 ✅ 确认「输入监控」同样已开启，两项权限缺一不可。 ✅ 改动权限开关后重启应用再验证。
修改配置后未重启应用
✅ 多数配置项只在启动时读取，改完先重启应用。 ✅ 从菜单栏退出 Mac Mouse Fix 再重新打开，做一次完整加载。 ✅ 重启后仍不对，用 Restore Defaults 对比确认当前值。
蓝牙鼠标间歇性断连
✅ 先换 USB 接收器或有线模式测试，确认问题只出现在蓝牙链路。 ✅ 只有蓝牙链路才复现的，到系统设置里删除配对记录后重新配对。 ✅ 重配对后依旧断连，联系鼠标厂商确认该型号在 macOS 下的兼容性。
参与项目
- 代码贡献：核心功能实现在 Helper/Core/ 目录，改代码前先通读对应模块。
- 文档与翻译：Markdown/LocalizedDocuments/ 下有 20 多种语言的本地化文档，可以补译或校对。
- 问题与功能反馈：到项目 Issues 提交，附上 macOS 版本和复现步骤。
侧键、滚动手感和手势这三项 macOS 留给第三方鼠标的缺口，装好 Mac Mouse Fix 之后都补上了。它没有改变鼠标本身，只是把事件到系统之间的链路接管过来，体验上的差别就在这里。
源码采用宽松开源许可（见仓库内 License），允许自由使用、修改和再分发。
【免费下载链接】mac-mouse-fixMac Mouse Fix - Make Your $10 Mouse Better Than an Apple Trackpad!项目地址: https://gitcode.com/GitHub_Trending/ma/mac-mouse-fix
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
