遠端 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":[]}'

清除後，必須中斷並重新建立遠端連線，再執行字元矩陣測試。如果問題消失，應將修正加入連線階段初始化指令碼，而不是要求成員手動點選設定。若問題依然存在，則應恢復主機基準設定，並將排查重點轉向用戶端的按鍵轉送規則。

識別用戶端攔截

如果某個組合鍵完全未送達遠端桌面，但其他組合鍵都正常，通常表示它先被本機系統或用戶端攔截。此時應改用其他測試組合，或調整用戶端設定；不要使用主機端重新映射來補償一個從未送達的按鍵。

驗收輸入法與自動化邊界

輸入法測試至少應涵蓋輸入來源切換、連續組詞、候選字翻頁、按 Enter 確認、全形與半形標點，以及在終端機和圖形介面應用程式中的一致性。密碼欄位、終端機安全輸入模式和部分遠端用戶端可能會限制組合輸入，因此不能只根據單一應用程式的測試結果下結論。

自動化工作不應依賴「目前的輸入法」。當指令碼產生設定檔、版本號或測試資料時，應直接寫入 UTF-8 檔案，或透過命令參數傳值。需要驅動圖形介面的測試，也應在開始前切換至約定的輸入來源，並將目前的輸入來源識別碼寫入記錄。如此即可將業務測試失敗與輸入環境漂移區分開來。

對於 VMOak 上的長期工作，建議將輸入來源清單和字元矩陣結果納入節點初始化記錄；短時間遠端操作則至少應保存用戶端版本與所選鍵盤配置。

重新連線後複測並建立基準

輸入驗收必須包含一次完整的中斷與重新連線。只關閉應用程式視窗並不足夠，應結束遠端連線、重新連接，再檢查目前的鍵盤配置、修飾鍵與輸入來源。如果只有在重新連線後才發生漂移，應優先檢查用戶端是否依連線設定覆寫鍵盤配置，以及登入時是否執行了設定指令碼。

最終基準可以維持得很精簡：

1. 約定一種邏輯鍵盤配置。
2. 只在用戶端或主機端其中一層交換修飾鍵。
3. 保存 AppleEnabledInputSources 與 UserKeyMapping 的輸出。
4. 完成字元矩陣及五組快捷鍵測試。
5. 分別在終端機與圖形介面應用程式中完成一次輸入法測試。
6. 中斷並重新連線後，再次測試關鍵項目。

處理輸入問題的原則，不是「調整到這次可以使用」，而是找出唯一負責轉換的層級，並確保下一次連線能得到相同結果。完成這套基準後，再安裝開發相依套件或接入自動化工作，後續發生問題時就更容易判定原因。

常見問題