从零构建QMK键盘的VIA支持：VENDOR_ID与PRODUCT_ID实战指南
当你花费数周时间手工打造了一把客制化机械键盘，却发现每次调整键位都需要重新编译固件时，那种繁琐感足以消磨所有创作热情。这正是VIA存在的意义——这个实时键位配置工具能让你的QMK键盘像商业产品一样即插即用。但要让VIA识别你的"独一无二"，关键在于正确配置那两个神秘的数字：VENDOR_ID和PRODUCT_ID。
1. VIA工作原理与核心概念
VIA本质上是一个通过USB HID协议与键盘通信的配置工具。当你在VIA界面点击"查找设备"时，它实际上在扫描所有USB设备的标识符。就像警察通过身份证号码确认身份一样，VIA依靠两组16进制数字识别合法设备：
- VENDOR_ID：通常代表键盘制造商（如0x04D8对应Microchip Technology）
- PRODUCT_ID：特定产品的型号标识（如0xECE9可能对应某款键盘PCB）
在QMK生态中，这两个参数定义在键盘目录下的config.h文件中。以下是典型配置示例：
/* USB Device descriptor parameter */ #define VENDOR_ID 0xFEED #define PRODUCT_ID 0x6060 #define DEVICE_VER 0x0001常见问题根源：超过80%的VIA识别失败案例源于这两个ID与VIA数据库不匹配。当你在VIA官方支持列表（caniusevia.com）看到自己的键盘显示"Unrecognized Device"时，大概率需要调整这些参数。
2. 获取合法设备ID的三种途径
2.1 使用VIA官方认证ID
最稳妥的方法是选用VIA已收录键盘的ID组合。操作流程：
- 访问VIA支持列表页面
- 找到与你的键盘PCB方案相同或相近的型号
- 在QMK源码仓库中搜索对应键盘的
config.h文件 - 复制其VENDOR_ID和PRODUCT_ID值
例如，许多GH60兼容PCB可以使用：
#define VENDOR_ID 0xFEED #define PRODUCT_ID 0x60602.2 申请自定义厂商ID（高级方案）
如果你开发的是商业产品，应当向USB-IF申请正式的Vendor ID。这是付费服务，但能确保全球唯一性：
- 访问USB-IF官网注册账户
- 提交企业资质证明
- 支付$6000年费获取专属VID
- 自行分配PID序列
注意：个人项目不建议此方案，可使用0xFEED这个QMK社区保留ID。
2.3 使用测试用ID范围
USB规范保留了特定范围的ID供开发者测试：
| ID类型 | 有效范围 | 使用场景 |
|---|---|---|
| Vendor ID | 0xF000-0xF0FF | 临时开发测试 |
| Product ID | 0x0000-0xFFFF | 任意自定义 |
示例配置：
#define VENDOR_ID 0xF055 #define PRODUCT_ID 0x13373. 键盘矩阵与keymap.json深度适配
即使ID配置正确，键位映射错误仍然会导致VIA显示异常。这是因为VIA需要精确知道每个物理按键在矩阵中的位置。
3.1 矩阵尺寸声明
在info.json中明确定义矩阵尺寸：
{ "keyboard_name": "My Custom KB", "url": "", "maintainer": "You", "matrix_pins": { "cols": ["GP0", "GP1", "GP2"], "rows": ["GP3", "GP4"] }, "layout": "LAYOUT_all" }3.2 创建匹配的keymap.json
VIA使用的键位映射文件需要严格对应物理布局。以下是一个60%键盘的片段：
{ "name": "My Layout", "layouts": { "key_count": 61, "layout": [ {"x":0, "y":0, "w":1, "h":1}, {"x":1, "y":0, "w":1, "h":1}, // ...其余键位定义 ] } }常见陷阱：
- 忘记定义旋钮或OLED等非标准控件
- 矩阵行列数声明与实际PCB不符
- 键位物理坐标超出面板范围
4. 完整实现流程与故障排除
4.1 分步实施指南
- 修改config.h：更新VID/PID并确认设备版本号
- 编译测试固件：
qmk compile -kb <keyboard> -km via - 刷新固件：使用QMK Toolbox或命令行工具
- 验证设备识别：在VIA中检查设备状态
- 导入keymap.json：通过FILE > Import Keymap加载布局
4.2 诊断工具推荐
当VIA无法识别设备时，这些工具能快速定位问题：
- USBTreeView：查看设备枚举详情
- QMK Console：监控调试输出
- VIA Debug Mode：启用开发者工具
4.3 典型错误对照表
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| 设备显示但键位错乱 | 矩阵定义不匹配 | 检查info.json的matrix_pins |
| VIA持续"Searching..." | VID/PID未注册 | 改用官方支持的ID组合 |
| 部分键位无响应 | 二极管方向错误 | 验证PCB原理图 |
| 固件刷入后无任何反应 | 引导加载程序未启动 | 短接重置引脚重新刷机 |
5. 高级技巧：动态功能扩展
通过VIA不仅可以修改基础键位，还能实现这些进阶功能：
- 宏命令录制：将复杂操作绑定到单一按键
- 层即时切换：无需编译即可调整功能层
- RGB灯光控制：实时调节背光模式和参数
- 鼠标模拟：将方向键设为鼠标移动
实现方法是在rules.mk中启用对应功能：
VIA_ENABLE = yes TAP_DANCE_ENABLE = yes RGBLIGHT_ENABLE = yes MOUSEKEY_ENABLE = yes记得在keymap.c中为这些功能保留专用键码：
enum custom_keycodes { KC_MACRO1 = SAFE_RANGE, KC_MACRO2, NEW_SAFE_RANGE };6. 维护与更新策略
当QMK版本升级时，VIA相关配置可能需要调整：
- 定期检查
qmk_firmware/keyboards/<your_kb>/via目录变化 - 使用
git diff对比官方VIA支持键盘的修改 - 订阅QMK Discord的#via频道获取更新通知
- 重大版本更新后重新验证所有功能
我在维护一个开源分体键盘项目时，曾因忽略VIA规范更新导致批量生产的PCB无法被新版本识别。后来我们建立了这样的版本矩阵：
| QMK版本 | VIA版本 | 测试状态 | 备注 |
|---|---|---|---|
| 0.18.1 | 2.1.1 | ✅ | 推荐生产版本 |
| 0.19.0 | 2.2.0 | ⚠️ | 存在层切换延迟问题 |
| 0.20.0 | 2.3.0 | 🚧 | 正在验证中 |
