远程 Mac 桌面的键盘布局、修饰键与输入法验收

远程接入云端 Mac 后，最容易被低估的故障不是网络中断，而是键盘“基本能用”却不完全正确：Command 与 Option 对调、数字行符号错位、中文候选键被客户端截获，或者自动化脚本输入的字符与人工操作不一致。这类问题若在配置工具链之后才发现，排查时很难区分故障来自本地系统、远程客户端还是 macOS 输入源。更稳妥的做法是把输入验收放在工作区初始化之前。

先固定三层输入链路

一次按键会依次经过本地键盘布局、远程客户端映射和云端 Mac 输入源。三层同时调整会让结果不可复现，因此先记录而不是立刻修改。

本地端要确认物理键盘类型、当前布局及远程客户端是否启用了“发送系统快捷键”“交换 Command 与 Option”之类的选项。云端 Mac 端则记录系统版本、已启用输入源和用户级按键重映射：

sw_vers
defaults read com.apple.HIToolbox AppleEnabledInputSources
defaults read com.apple.HIToolbox AppleCurrentKeyboardLayoutInputSourceID
hidutil property --get "UserKeyMapping"

若最后一条返回空数组，说明主机端没有通过 hidutil 增加用户映射。若存在映射，先保存输出，再判断它是否属于团队基线；不要在不知道来源时叠加第二套交换规则。

一次只允许一层负责修饰键转换。客户端已经交换按键时，主机端不要再做相同映射。

用字符矩阵定位布局错位

不要只打开编辑器输入几个字母。应在纯文本窗口中按固定顺序测试，避免编辑器快捷键、代码补全或自动替换干扰结果。

测试符号时应明确团队采用的逻辑布局，例如美式 ANSI，而不是按成员各自键帽判断。远程机器服务于自动化任务时，统一逻辑布局比复制每位开发者的本地习惯更可靠。

排除文本替换干扰

若直引号、短横线或连续空格被自动替换，先在纯文本模式复测。字符本身正确而编辑器结果不同，问题通常属于应用级文本处理，不应继续修改系统键盘映射。

单独验收修饰键和快捷键

修饰键故障通常具有方向性：Command+C 正常，不代表 Option+数字、Control+字母或 Command+Shift 组合也正确。建议建立最小快捷键集，覆盖复制、窗口切换、按词移动、大小写组合和客户端保留键。

如果确认主机端残留了错误映射，可在当前登录会话中清空：

hidutil property --set '{"UserKeyMapping":[]}'

清空后必须断开并重新建立远程会话，再执行字符矩阵。若问题消失，应把修复放在会话初始化脚本中，而不是让成员手工点击设置。若问题仍在，则恢复主机基线，将注意力转向客户端按键转发规则。

识别客户端截获

某个组合键完全没有到达远程桌面，但其他组合正常，通常意味着本地系统或客户端先消费了它。此时应更换测试组合或调整客户端设置，不要用主机端重映射补偿一个从未送达的按键。

验收输入法与自动化边界

输入法测试至少覆盖输入源切换、连续组词、候选翻页、回车确认、全角与半角标点，以及在终端和图形应用中的一致性。密码框、终端安全输入模式和部分远程客户端可能限制组合输入，因此不能只在一个应用中得出结论。

自动化任务不要依赖“当前输入法”。脚本生成配置文件、版本号或测试数据时，应直接写入 UTF-8 文件，或通过命令参数传值。需要驱动图形界面的测试，也应在开始前切换到约定输入源，并把当前输入源标识写入日志。这样可以把业务测试失败与输入环境漂移分开。

对于 VMOak 上的长期任务，建议把输入源清单和字符矩阵结果作为节点初始化记录的一部分；短时远程操作则至少保存客户端版本与布局选择。

重连后复测并形成基线

输入验收必须包含一次完整断开与重连。仅关闭应用窗口不够，应结束远程会话、重新连接，再检查当前布局、修饰键和输入源。若重连后才出现漂移，重点检查客户端是否按连接配置覆盖布局，以及登录时是否运行了设置脚本。

最终基线可以保持很短：

1. 约定一种逻辑键盘布局。
2. 只在客户端或主机端其中一层交换修饰键。
3. 保存 AppleEnabledInputSources 与 UserKeyMapping 输出。
4. 跑完字符矩阵和五组快捷键。
5. 在终端与图形应用各完成一次输入法测试。
6. 断开重连后重复关键项。

输入问题的处理原则不是“调到这次能用”，而是找到唯一负责转换的层，并让下一次连接得到相同结果。完成这套基线后，再安装开发依赖或接入自动化任务，后续故障会更容易归因。

常见问题