本文详解virtualbox `ikeyboard.putscancodes()` 接口使用的**物理键盘扫描码（scan code）**机制，阐明其与java/windows中虚拟键码（vk_p = 0x50）的本质区别，并提供可运行的编码转换方案与实用建议。
在使用 VirtualBox Java SDK 控制虚拟机键盘输入时（如调用 k.putScancodes(Arrays.asList(25, 25 | 0x80)) 发送字母 P），开发者常困惑于：为何 Java 的 KeyEvent.VK_P 和 Windows 文档中的虚拟键码均为 0x50（即 ASCII 码值），而 VirtualBox 却要求传入 25？答案在于——VirtualBox 的 IKeyboard 接口不接受虚拟键码（Virtual Key Code），而是直接模拟物理键盘行为，接收的是底层硬件级的扫描码（Scan Code）。
扫描码 vs 虚拟键码：根本差异
-
扫描码（Scan Code）：由物理键盘芯片生成，表示“某个物理按键被按下/释放”，与字符无关，且依赖键盘布局和历史标准（如 IBM PC/XT 的 Scan Code Set 1）。例如：
- 25 表示 P 键按下（make code）；
- 25 | 0x80 = 153（即 0x99）表示 P 键释放（break code）。
- 虚拟键码（Virtual Key Code）：是操作系统抽象层定义的逻辑常量（如 VK_P = 0x50），用于统一处理不同键盘布局下的语义操作（如“用户想输入字母 P”），需由键盘驱动将扫描码翻译而来。
VirtualBox 为保证跨平台兼容性与精确硬件仿真，选择绕过宿主机 OS 的键盘驱动栈，直接向客户机注入原始扫描码——这正是 putScancodes() 接口的设计定位：低阶、无状态、与 BIOS/UEFI 引导阶段兼容。
实际编码：使用 Scan Code Set 1（VirtualBox 默认）
VirtualBox 使用的是经典的 IBM PC/XT Scan Code Set 1（也称 "AT Set" 或 "Set 1"）。以下是常用字符对应关系（含 Shift 修饰）：
| 字符 | 按下扫描码 | 释放扫描码 | 备注 |
|---|---|---|---|
| P | 25 | 153 | 25 \| 0x80 |
| 2 | 3 | 131 | 主键盘区数字键 |
| b | 48 | 176 | 小写 b（需配合左 Shift） |
| Shift（左） | 42 | 170 | 必须先按再松，才能生效 |
✅ 正确发送小写字母 p 的完整流程（含 Shift 控制）：
Java项目代码review工具。分析Git变更+完整调用链路上下文，推断业务需求，进行多维度评分和分类汇总，生成完整PRD文档。包含细粒度Java代码审查清单（Null安全、异常处理、Streams、并发、equals/hashCode、资源管理、API设计、性能、MyBatis/ORM、事务边界、SQL/DD...
// 模拟按下 Left Shift + P → 输出 'p'
k.putScancodes(Arrays.asList(
42, // Left Shift down
25, // P down
153, // P up
170 // Left Shift up
));⚠️ 注意事项：
- 必须成对发送按下/释放码，否则客户机会卡在“按键持续按下”状态；
- 修饰键（Shift/Ctrl/Alt）需显式控制，无自动修饰逻辑；
- 不同键盘布局（如 AZERTY、Dvorak）下，同一物理键的扫描码不变，但映射字符不同——VirtualBox 不做布局转换；
- putScancodes() 是阻塞式调用，若客户机无响应或键盘驱动异常，可能超时。
更优替代方案（推荐用于实际项目）
尽管 IKeyboard 精确可靠，但手动管理扫描码易错、可维护性差。根据使用场景，建议优先考虑以下更高层方案：
- ✅ Guest Additions + Clipboard / Drag & Drop：启用后，可通过 IClipboard 向客户机粘贴文本（支持 UTF-8）；
- ✅ VNC / RDP 连接：使用 IVRDEServer 或外部 VNC 客户端发送 Unicode 字符串；
- ✅ SSH / Web API 驱动客户机脚本：在客户机预装轻量服务（如 Python HTTP server），通过 curl 触发命令，规避所有键盘仿真复杂度；
- ✅ IConsole.keyboardPutScancode() 已弃用？ 当前 VirtualBox SDK（7.x+）仍保留该接口，但官方文档明确标注其为“low-level”——仅推荐自动化测试或调试场景使用。
总之，25 不是 bug，而是 VirtualBox 对 PC 架构真实性的坚守。理解扫描码本质，才能驾驭底层输入控制；而面向生产环境，则应善用更高抽象层的通信通道，兼顾健壮性与开发效率。
