Unity中KeyCode枚举值与实际按键不匹配怎么办？

Question

在Unity中，KeyCode枚举值与实际物理按键不匹配是常见问题，尤其在多语言键盘（如法语AZERTY、德语QWERTZ）、非美式布局或使用外接机械键盘/游戏手柄时。典型表现为：按下「W」键却触发KeyCode.S，或「Shift」被识别为KeyCode.LeftShift失效。根本原因在于Unity底层依赖操作系统原始扫描码（scan code）与键盘布局映射，而KeyCode枚举是基于美式QWERTY硬编码的逻辑键名，并非实时感知当前系统键盘布局。此外，Input.GetKeyDown(KeyCode.W)在非英文系统中可能无法响应用户认知中的“前移键”。该问题在WebGL、macOS（无CapsLock事件）、部分Linux发行版及Steam Deck等设备上尤为突出。解决方案需绕过KeyCode直接读取扫描码（通过InputSystem包的Keyboard.current[key].wasPressedThisFrame），或结合System.Globalization.CultureInfo.CurrentCulture进行布局适配，而非依赖KeyCode枚举做硬编码判断。

Answer 1

```html

一、现象层：跨区域键盘按键行为错位的典型表现

• 法语AZERTY用户按物理「W」键（位于QWERTY的「S」位置），Input.GetKeyDown(KeyCode.W)始终不触发，而KeyCode.S却响应——实际映射为法语布局下的「Z」键功能；
• 德语QWERTZ用户按下左Shift，Input.GetKeyDown(KeyCode.LeftShift)返回false，但Input.GetKey(KeyCode.RightShift)意外为true（因系统将物理左Shift报告为右Shift扫描码）；
• Steam Deck在桌面模式下启用IBus输入法后，所有KeyCode.Backspace事件丢失，但Keyboard.current.backspaceKey.wasPressedThisFrame仍可靠触发；
• macOS Catalina+ WebAssembly构建中，CapsLock状态变更无KeyCode.CapsLock事件回调（OS级屏蔽），且Event.current.keyCode在IM输入期间恒为KeyCode.None。

二、机制层：Unity KeyCode设计范式与操作系统语义鸿沟

Unity的KeyCode枚举本质是静态符号表，其值（如KeyCode.W = 119）直接绑定ANSI QWERTY逻辑键名，而非动态解析：

平台	底层输入源	KeyCode映射依据	是否感知当前Layout
Windows	WM_KEYDOWN扫描码 → Virtual Key Code	硬编码VK_W=87 → KeyCode.W	否（忽略HKLM\SYSTEM\CurrentControlSet\Control\Keyboard Layout）
macOS	NSEvent keyCode（已过时）或CGEventGetIntegerValueField	固定映射kVK_ANSI_W=13 → KeyCode.W	否（不调用TISCopyCurrentKeyboardLayoutInputSource）
WebGL	DOM KeyboardEvent.code	强制转译为QWERTY逻辑名（e.g. "KeyZ"→KeyCode.Z）	否（忽略navigator.language & KeyboardEvent.layoutMap）

三、诊断层：四步定位法验证键盘布局失配根源

1. 扫描码探针：使用InputSystem包捕获原始扫描码：Keyboard.current.GetKey(Scancode.FromInt(0x11)).wasPressedThisFrame（0x11为W在QWERTY的扫描码）；
2. 布局比对：运行System.Globalization.CultureInfo.CurrentCulture.TextInfo.ANSICodePage获取当前键盘ID（如1036=French），交叉查证Keyboard.current["w"].displayName返回值；
3. 事件溯源：重写OnGUI()监听Event.current.type == EventType.KeyDown，打印Event.current.keyCode与Event.current.character差异；
4. 跨平台验证：在Linux终端执行dumpkeys --full-table | grep -A5 "keycode 25"确认物理键25在当前布局下的字符映射。

四、解法层：三层兼容性架构设计

graph TD A[输入源] --> B{输入系统选择} B -->|Legacy Input| C[KeyCode硬编码
❌ 多语言失效] B -->|Input System 1.x| D[Scancode + Layout-Aware Key
✅ 支持AZERTY/QWERTZ] B -->|Input System 2.x| E[Keyboard.current[key].wasPressedThisFrame
✅ 动态布局感知] D --> F[通过Keyboard.current.GetScancodeForKeyCode(KeyCode.W)反查] E --> G[结合Keyboard.current.GetDisplayNameForScancode获取本地化键名]

五、实施层：生产就绪代码模板

// ✅ 基于Input System 2.1+ 的布局无关移动控制
public class LocalizedMovement : MonoBehaviour
{
    private Keyboard _keyboard;
    private Scancode _forwardScan;
    
    void OnEnable() {
        _keyboard = Keyboard.current;
        // 根据当前Culture动态绑定“前移”物理键
        var culture = CultureInfo.CurrentCulture.Name;
        _forwardScan = culture switch {
            "fr-FR" => Scancode.FromInt(0x2C), // AZERTY的Z键扫描码
            "de-DE" => Scancode.FromInt(0x11), // QWERTZ的W键扫描码  
            _ => Scancode.FromInt(0x11)         // 默认QWERTY
        };
    }
    
    void Update() {
        if (_keyboard != null && _keyboard.GetKey(_forwardScan).wasPressedThisFrame) {
            transform.Translate(Vector3.forward * Time.deltaTime * 5f);
        }
    }
}

六、演进层：未来兼容性路线图

• Unity 2023.2+ 已实验性支持Keyboard.current.layout API，可实时获取KeyboardLayout.French等枚举；
• WebGL 2.0规范草案要求浏览器暴露navigator.keyboard.getLayoutMap()，Unity正对接该标准；
• Steam Deck厂商固件已开放/sys/class/input/event*/device/capabilities/ev扫描码映射表，可通过NativePlugin读取；
• Unity官方Roadmap明确将KeyCode标记为[Obsolete("Use Scancode or Keyboard.current instead")]（预计2025 LTS版）。

```