Mac Mouse Fix 按键捕获（Captured Buttons）完全指南：从原理到恢复原始功能的三种方案
Mac Mouse Fix 按键捕获（Captured Buttons）完全指南：从原理到恢复原始功能的三种方案
安装 Mac Mouse Fix（MMF）后，你可能遇到过提示“鼠标按键已被 Mac Mouse Fix 捕获（captured）”的弹窗。这篇指南将完整解释“捕获”的底层机制、它为什么会导致 Chrome 前进/后退、终端中键粘贴、Blender 中键旋转等“老功能”失效，并给出三套恢复方案：在捕获状态下用 MMF 动作还原功能、彻底解除捕获、以及整体关闭 MMF。读完你可以独立判断自己鼠标上的哪些按键被捕获、如何精准解除，并理解“Back / Forward / Middle Click / Scroll & Navigate”等 MMF 动作在源码层面是如何模拟原始按键行为的。本文内容基于仓库文档 CapturedButtonsMMF3.md 及其配套源码展开。
什么是“捕获（capturing）”一个鼠标按键？
当一个鼠标按键被 Mac Mouse Fix 捕获后，其他 App 和 macOS 就再也“看不见”这个按键了——按键事件不会再派发到前台应用，该按键原本承载的系统级功能也随之失效。
典型例子：正常情况下，你可以在 Chrome 里用鼠标侧键（按键 4 和 5）执行“后退 / 前进”。但当这两个侧键被 MMF 捕获后，这个功能不再生效，侧键只会触发你在 MMF 中为它们绑定的动作。
MMF 为什么要这样做？ 捕获的本质是把按键事件从系统事件流中“拦截”下来，只交给 MMF 处理，从而避免在使用 MMF 手势时同时误触其他 App 的功能。文档中给出的场景很直白：
如果你把按键 4 的“点击并拖动”映射为“切换桌面”，那么在拖动过程中，Chrome 会同时收到一次“后退”事件，导致页面一起后退。
用源码佐证：MMF 的 Helper 进程通过 CGEventTapCreate(kCGHIDEventTap, ...) 在 HID（硬件输入）层级挂载事件 Tap，只监听中键及其他按键（左右键在 _buttonParseBlacklist 中被排除，见 ButtonInputReceiver.m）。事件在到达前台 App 之前就被这个 Tap 截获，这正是“其他 App 无法再看到该按键”的实现基础。需要明确的是，捕获只针对你在 MMF 中配置过映射（remaps）的按键，没有配置的按键不会受影响。
如何判断哪些按键正在被 MMF 捕获？
方法非常直观：凡是出现在 “Buttons” 标签页左侧列表里的按键，就是正在被捕获的按键。
打开 Mac Mouse Fix 主界面，进入 “Buttons” 标签页（对应源码中的 ButtonTabController.swift 及其 Remap 表格视图），左侧分组中列出的每一个按键条目都代表一组生效中的映射。下图中的 “Middle Button”、“Button 5”、“Button 4” 就是三个正在被捕获的按键：
如何阻止 MMF 捕获某个按键（解除捕获）？
解除捕获同样只需在界面里操作：删除 “Buttons” 标签页中该按键的所有条目。
每个条目左侧都有一个 “-” 按钮，点击即可删除该条映射。当一个按键在 MMF 中**不再有任何绑定（bindings）**时，它就不再被捕获，行为会恢复得“和 Mac Mouse Fix 被禁用时完全一样”——即按键事件原样透传给系统。下图演示了如何通过点击两个高亮的 “-” 按钮，把 “Button 4” 从被捕获状态中释放出来：
三种方式恢复按键的原始功能
如果你怀念安装 MMF 之前按键的行为，有三条路径可选，按“干预程度”从小到大排列：
- 保持按键被捕获，但在 MMF 内为它分配能还原原始功能的动作（推荐，最灵活）；
- 解除捕获——删除该按键在 MMF 中的全部绑定，让它完全回归系统原生行为；
- 整体关闭 Mac Mouse Fix——在 “General > Enable Mac Mouse Fix” 处关闭总开关，此时 MMF 完全不干预你的鼠标（该开关对应的界面元素见 Main.storyboard）。
下面重点展开方案 1，因为它能让你既保留按键在 MMF 中的新功能，又找回原来的用途。
方案 1：不解除捕获，用 MMF 动作还原原始功能
文档给出了一张“按键 → 原始功能 → 对应 MMF 动作”的对照表，是本文最核心的可操作内容：
| 按键 | 原始功能 | MMF 中应分配的动作 |
|---|---|---|
| 中键 | 在浏览器中以新标签页打开链接 | 'Middle Click'（可绑定到按键的单击） |
| 中键 | 在终端中粘贴文本 | 'Middle Click'（可绑定到按键的单击） |
| 按键 4 / 按键 5 | 在 Chrome 等 App 中后退 / 前进 | 'Back' / 'Forward'（可绑定到按键的单击） |
| 中键 | 在 Blender 等 3D 软件中环绕（Orbit）观察物体 | 'Scroll & Navigate'（可绑定到按键的点击并拖动） |
'Middle Click' 动作：还原终端粘贴与浏览器中键行为
“Middle Click” 动作在源码层面对应 kMFActionDictTypeMouseButtonClicks，通过 <a href="https://link.gitcode.com/i/75ce11978881ecc48fb2157c9f088823" target="_blank">ModificationUtility postMouseButtonClicks:button.intValue nOfClicks:nOfClicks.intValue] 向系统重新注入一次中键点击（见 [Actions.m）。由于它注入的是真实的中键事件，终端的中键粘贴、浏览器的中键新开/关闭标签页等系统原生语义都会被正确触发。
'Back' / 'Forward' 动作：还原 Chrome、VSCode 等 App 的后退 / 前进
这是 3.0.6 版本起升级过的“Universal Back and Forward”机制。其实现位于 Actions.m，核心逻辑是根据鼠标指针下方 App 的 bundle ID 选择不同的“后退/前进”实现方式：
- 对大多数非 Apple 应用（含 VSCode、Chrome、Cursor 等），默认模拟真实的鼠标按键 4 / 5 点击（
bfmethod_mouseButton，见 Actions.m）——这正是文档所说“Back/Forward 动作在游戏和专业 App 中会模拟 MB 4/5 点击”的原因，因此你可以在这些 App 内把 MB 4/5 重新映射到自己的功能上，且能正常生效； - 对 Apple 原生 App（如 Safari、Finder），默认使用导航轻扫（navigation swipe），模拟两指触控板手势；
- 对 Zotero、系统设置、App Store、Acrobat 等特定应用，则改用
⌘[/⌘]、⌘←/⌘→等快捷键组合（对应bfmethod_commandBracket、bfmethod_commandLeftRightArrow等分支）。
这份针对不同应用的兼容性测试记录完整保存在 Universal Back and Forward.md 中（其中列出了 Chrome、Edge、Slack、Notion、JetBrains IDE 等大量 App 的实测结论），如果你关心的 App 不在默认覆盖范围内，可以去那里查证。
'Scroll & Navigate' 动作：还原 Blender 等 3D 软件的中键环绕
“Scroll & Navigate” 会模拟双指触控板滑动，从而在 Blender 等支持触控板手势的 3D 软件中触发“环绕观察（Orbit）”。这得益于 MMF 底层通过 TouchSimulator.m 注入仿触控板事件（导航轻扫见 postNavigationSwipeEventWithDirection:，在 Actions.m 中被调用）。同样的机制还能顺带还原 Chrome 等浏览器中的页面后退/前进。文档也给出了一条已知限制：如果电脑负载过高导致系统变慢，模拟的触控板事件可能变得不够跟手（项目方注明“正在改善这一点”）。
关于“单击”动作的一个重要注意点
表格中反复强调 “Middle Click”、“Back / Forward” 只能绑定到单击（click），而不能绑定到“点击并拖动（click and drag）”。原因是：MMF 在触发这类动作时会把 mouseDown 和 mouseUp 两个事件一次性连续发出（原文注释：MMF sends the mouseup and mousedown event at once），这样做是为了避免与同一按键上绑定的其他 MMF 手势互相干扰。所以如果你需要“拖动中键来环绕”这类持续按住的行为，请使用 'Scroll & Navigate' 而不是 'Middle Click'。
方案 2：解除捕获，让按键完全回归系统
删除该按键在 “Buttons” 标签页中的全部条目（见上文“如何阻止捕获”一节）即可。解除后该按键的事件将完全透传，行为与未安装 MMF 时无异。从源码角度理解：MMF 的 Helper 根据配置生成“remaps”（映射表，见 Remap.m），当一个按键在映射表中不再有任何触发器时，SwitchMaster.swift 会关闭对应的事件处理路径，按键输入不再被拦截。
方案 3：整体关闭 Mac Mouse Fix
在 “General > Enable Mac Mouse Fix” 关闭总开关（对应 Main.storyboard 中的开关控件）。此时 MMF 不干预鼠标的任何输入，所有按键都不会被捕获。注意这与“退出 App”不同——MMF 的 Helper 常驻运行，关闭这个开关才是真正停用全部改键能力的入口。
常见问题排查速查
- 终端里中键粘贴 / 浏览器中键新开标签页失效 → 中键被捕获，为中键分配 'Middle Click' 动作即可还原；
- Blender 里中键拖动无法环绕 → 为中键的“点击并拖动”分配 'Scroll & Navigate'；
- Chrome / VSCode 里侧键无法后退前进 → 为按键 4 / 5 分配 'Back' / 'Forward'（3.0.6 起会自动适配不同 App 的实现方式）；
- 游戏或专业软件里自定义的侧键映射失效 → 'Back' / 'Forward' 会模拟真实的 MB 4/5 点击，可在这些软件内重新映射 MB 4/5；
- 想彻底恢复某个按键的系统原生行为 → 删除该按键的所有条目（解除捕获）；
- 想确认当前到底捕获了哪些按键 → 查看 “Buttons” 标签页左侧列表，凡出现者即被捕获。
延伸阅读
滚动滚轮同样存在“捕获”机制，如果滚轮被捕获后你无法用 MOS、Logi Options 等第三方平滑滚动软件接管滚动，可阅读配套文档 Captured Scroll Wheels，其结构与本文完全对应（什么是滚轮捕获、如何判断、如何解除）。需要进一步了解 “Buttons” 标签页的映射表格界面结构，可查看 ButtonTabController.swift 与 RemapTableController.m；想要深入探索 “Back / Forward” 的跨应用适配细节，Universal Back and Forward.md 是最佳入口。