给键盘加VIA支持这件事我在不同主控、不同配列的板子上折腾过很多次。第一次搞的时候其实挺狼狈的——固件编译得明明白白刷进去以后键盘也能打字但打开VIA软件就是死活认不出设备。排查到最后才发现问题压根不在VIA_ENABLE有没有开而在VENDOR_ID和PRODUCT_ID这两个看似不起眼的参数上。这篇就围绕整个流程把从零开始给QMK键盘加VIA支持的每一步拆开讲清楚重点讲透VID/PID配置以及刷完固件后设备不认的各种坑。这篇文章适合三类人刚拼好套件想让键盘能可视化改键的新手手里有量产键盘想魔改固件加VIA的老玩家以及看了QMK文档但被零散术语卡住、需要一份完整实操路径的中间层用户。1. VIA到底解决了什么问题——以及它在QMK里的工作方式先说清楚VIA是什么不然很多人会把它和QMK Configurator、Vial搞混。1.1 实时调参和重新编译的本质区别QMK默认的工作方式是编译-刷写-验证改一次键位就要改一次keymap.c重新编译整个固件再通过bootloader刷进键盘。这个流程本身没问题但每次改个键都要走一遍确实麻烦。VIA的全称是Visual Interactive Application它做的事情简单说就是固件里内置一个“可动态改写的键位表”VIA软件通过USB与键盘通信直接在运行时改写这个表不需要重新编译和刷写固件。你在VIA界面里把A键改成B键点保存键盘立刻就能用新键位重启也不会丢。Vial和VIA是同一思路区别在于Vial支持更多运行时调试功能但对固件体积和主控Flash的要求更高这里不展开后面说到选型时再提。1.2 VIA在QMK固件侧的三层依赖要让VIA跑起来固件侧必须同时满足三个条件缺一个都不行条件作用缺了会怎样VIA_ENABLE yesrules.mk编译时把VIA动态键位映射代码编进固件编译出来就是普通固件VIA软件无法识别Raw HID功能QMK默认支持VIA软件通过Raw HID与键盘通信读写键位表没有这个软件与固件之间没有“通道”足够的主控存储空间EEPROM或模拟EEPROM保存你改过的键位、灯效、宏等配置改完一断电就恢复原样第三点特别容易被忽略。以RP2040树莓派Pico芯片为例它没有真正的EEPROMQMK通过模拟EEPROM把数据存在Flash里。只要Flash空间够就没问题但一些老主控比如早期STM32F303遇到过动态键位映射和RGBLIGHT同时开启导致空间紧张的情况编译时会直接报错。1.3 为什么我建议DIY键盘优先考虑加VIA如果你是自组键盘无论是GH60、YD60BLE还是各种“PCB没标名字的套件”只要主控是常见的ATmega32U4、STM32、RP2040之一基本都能上VIA。加VIA之后最大的好处不是“方便”而是降低后续迭代成本——之后再想换键位、调灯效、改宏都不用动固件直接在软件里拖一拖就行。不过要提醒一句VIA不是万能的。它不能改键盘矩阵的物理定义不能改层的个数QMK默认最多4层VIA也不超过这个不能改按键的编码类型上限。矩阵定义、层数、宏长度这些属于固件编译期的硬限制VIA只负责“软件期”的调整。2. 开工前的检查清单从固件源码到编译环境的准备在动手之前先确认你的“底盘”是正常的。很多人一上来就在一个连默认键位都没验证过的固件上改配置最后出问题了根本分不清是固件本身的问题还是VIA支持加得有问题。2.1 找到你的键盘在QMK仓库里的位置QMK官方仓库的目录结构是qmk_firmware/keyboards/厂商名/键盘名/。拿最常见的GH60来说它的路径大致是qmk_firmware/keyboards/gH60/但注意REV系列和量产系列不一样有些键盘有多个硬件版本比如gH60/rev1、gH60/rev2每个版本有自己的rules.mk和info.json。改错版本目录是新手最常见的错误没有之一。如果找不到你的键盘说明你的键盘固件不在QMK官方仓库里。这时候你需要先把键盘的固件源代码放到qmk_firmware/keyboards/下然后通过qmk compile -kb 你的键盘名 -km default验证路径是否正确。2.2 检查键盘目录下的关键文件进入键盘目录后重点看三个文件rules.mk这个文件里写着固件的各种启用选项VIA_ENABLE就在这。info.json新版QMK用这个文件统一管理键盘元数据包括VENDOR_ID、PRODUCT_ID、矩阵大小、RGB灯效配置等。老版是config.h新版已经逐步迁移但有些键盘目录里还保留着config.h注意别改错。keymaps/目录这里是键位配置default和via是常见命名。如果官方仓库没有提供via键位目录你需要在keymaps/下新建一个via目录里面放一个最基本的keymap.c最简单的做法是直接复制default目录的keymap.c进去。2.3 编译环境与QMK CLI强烈建议使用QMK官方提供的命令行工具这是目前最省事的方案。安装方式官方文档有大致是# macOS 或 Linux python3 -m pip install --user qmk qmk setup# WindowsWindows 10/11 MSYS2 # 官方推荐用 MSYS2 终端在 MSYS2 里执行 pacman -S --needed base-devel git python python-pip python3 -m pip install --user qmk qmk setupqmk setup会帮你把qmk_firmware仓库克隆到本地同时装好编译器和依赖。跑完这一步先验证环境qmk compile -kb 你的键盘名 -km default如果你能正常编出一个hex或bin文件说明环境没问题。这一步极其重要它相当于“基线验证”。你后面改配置之后如果编译报错就有对照物可以排查。如果连默认键位都编译不过先解决环境问题不要继续往下走。2.4 建议先把默认固件刷进去验证硬件严格来说这一步不是必须的但我个人强烈建议做。把默认固件刷到键盘里确认键盘能打字、灯光正常、各按键触发正确然后再开始加VIA。否则等你刷了带VIA的固件发现键盘某些键没反应你很难判断是硬件的锅还是VIA的锅。具体的刷写方式和bootloader进入方式每种PCB都不一样常见的有键盘背面有个复位小孔用针戳一下就进入bootloaderQK_BOOT按键默认键位里通常有键盘上的某个组合键比如Fn Esc进入刷写模式进入bootloader后用qmk flash -kb 你的键盘名 -km default烧录。烧录完成后验证每个键位都能正常用。3. VENDOR_ID和PRODUCT_ID详解为什么改这两个值能让VIA认你的键盘这是全文的重头戏。很多人加VIA支持时只记得在rules.mk里加VIA_ENABLE yes忽略了info.json里的VID/PID配置。结果编译刷写一气呵成打开VIA却找不到设备最后卡在“明明固件有VIA功能但软件就是不认”的尴尬境地。3.1 它们在USB协议里到底是什么VENDOR_ID厂商ID简称VID和PRODUCT_ID产品ID简称PID是USB协议里的设备识别字段。VID标识设备的制造商。USB-IF组织统一分配正规厂商需要花钱申请。QMK默认用的VID是0xFEED这是QMK社区通用的“占位符”自己玩完全够用。PID标识同一厂商下的具体产品型号。在同一个VID下不能有两个设备用相同的PID否则操作系统和软件都无法区分它们。对于VIA软件来说它识别键盘的方式就是读这两个ID固件上报的VID/PID必须和VIA软件里加载的键盘JSON文件里写的VID/PID完全一致。对不上就不认。3.2 在QMK源码里怎么改新版QMK推荐在info.json里配置格式如下{ usb: { vid: 0xFEED, pid: 0x0000, device_version: 1.0.0 } }注意VID和PID都是十六进制数必须写成0x开头的字符串。PID一般有4个十六进制位0x0000到0xFFFF但不建议用0x0000有些系统会对全零ID做特殊处理。device_version不是必填但建议写上。VIA在某些情况下会检查设备版本版本不匹配也可能导致识别问题。你还可以在JSON文件里加manufacturer和keyboard_name字段{ manufacturer: 你的名字或团队名, keyboard_name: 你的键盘型号, usb: { vid: 0xFEED, pid: 0x6060, device_version: 1.0.0 } }如果某个老键盘还在用config.h配置也可以在这两个地方改#define VENDOR_ID 0xFEED #define PRODUCT_ID 0x6060info.json的优先级高于config.h如果两边都写了以info.json为准。3.3 改之前先想明白哪些场景该改、哪些场景不该改这是很多人没想清楚的问题。不需要改VID/PID的场景你只是想自用键盘固件是QMK官方仓库里的现成键盘那么直接用默认的VID/PID就行。QMK默认的0xFEED就是给这种情况用的。必须改VID/PID的场景你有两个或以上的键盘都沿用QMK默认的0xFEED/0x0000同时插在电脑上VIA会“打架”——它分不清哪个是哪个。你要把固件发布出去给别人用或者上传到VIA的官方仓库。这时候必须给你的键盘分配一个独立的VID/PID否则别人的VIA设备列表里会显示两个一模一样的“未知设备”。你的键盘已经有一个量产版本固件里有自己的VID/PID但你想魔改固件加VIA。这时候尽量保留原有的VID/PID这样原来的驱动逻辑也能继续生效。独立PID要不要申请如果你是自用不需要去USB-IF申请直接用0xFEED加一个不冲突的PID就行。如果以后真要做产品那一定要申请正规VID这里不展开。3.4 改错的后果远比你想的严重改错VID/PID最直接的表现就是系统把它当成一个新设备。你插上键盘Windows会“叮咚”一声然后开始装驱动——如果这个VID/PID以前从没见过Windows就会装一个“未知USB设备”或者“HID键盘”的通用驱动。表面看键盘还能打字但VIA软件就是找不到它。更麻烦的是如果VID/PID改得太随意和别的常见设备撞车了还会引发驱动冲突。我自己就遇到过一次把PID设成了某个游戏外设的同款结果Windows直接优先加载了那个外设的驱动键盘的所有多媒体功能全部失效折腾了一下午才排查出来。所以改VID/PID的正确姿势是保持VID为0xFEED不变或你已有的VID在0x0001到0xFFFF之间选一个没被QMK官方仓库其他键盘用过的PIDQMK官方仓库里每个键盘的PID都是公开的动手前花两分钟去qmk_firmware/keyboards里搜一下确保不撞车这比事后排查省事得多。4. 从rules.mk加到固件刷入VIA支持使能的完整实操环境准备好了VID/PID心里有数了下面进入正题。我会按实际操作顺序一步一步来每一步都说明为什么这么做。4.1 启用VIArules.mk里的改动进入你的键盘目录找到rules.mk或者在keymaps/via/目录下新建一个rules.mk加上VIA_ENABLE yes这里有一个版本差异旧版QMK里加这一行就能启用VIA。但新版QMK对VIA的支持有一些额外要求比如某些键盘需要同时启用LTO_ENABLE yes链接时优化来减小固件体积。如果编译时提示空间不够加上这行再试。另一个常见问题是如果你同时启用了RGBLIGHT_ENABLE yes或RGB_MATRIX_ENABLE yesVIA需要额外配置灯效通道否则VIA软件里“灯效”一栏会一直显示不可用。这个后面JSON文件部分会提到。如果你在keymaps/via/目录下单独建了rules.mk那这个文件里的配置只对via键位图生效。这样你可以在不改变默认键位图的前提下单独为VIA准备一份固件。这种做法我比较推荐因为它的影响范围可控出问题也容易回退。4.2 准备VIA能识别的键盘JSON文件这一步和固件编译同样重要却经常被忽略。简单说VIA软件本身不知道你键盘的矩阵图、层数、RGB配置长什么样它需要加载一个JSON文件来获取这些信息。这个JSON文件放在两个地方之一VFA官方仓库如果键盘是量产键盘且已提交到qmk_firmware官方仓库VIA软件会通过在线仓库自动匹配键盘JSON无需手动导入。这种情况比较少见大部分DIY键盘都没在VIA官方列表里。本地手动导入在VIA软件里选择“启用未定义键盘”然后手动加载JSON文件。JSON文件的结构长这样简化版{ name: 你的键盘名, vendorId: 0xFEED, productId: 0x6060, lighting: none, matrix: { rows: 5, cols: 15 }, layouts: { keymap: [ [ {x: 0, y: 0}, {x: 1, y: 0}, ... 依次列出所有按键的坐标 ] ] } }这个JSON文件的VID/PID必须和你固件里设置的完全一致包括大小写格式。0xFEED和0xfeed在VIA看来可能不是同一个值建议全部用大写。关于JSON文件的生成有几个途径如果键盘在QMK官方仓库里可以直接在编译时用qmk json2c或手动从info.json转换生成。如果键盘不在官方仓库可以根据自己的info.json手动编写但按键坐标部分相当繁琐错一个坐标键位就错位。推荐做法先查一下QMK官方仓库里有没有你的键盘。有的话直接在qmk_firmware/keyboards/你的键盘名/keymaps/via/keymap.c基础上改没有的话可以参考别人同配列键盘的JSON文件改写成自己的。我见过不少人卡在这一步。固件大小、VIA_ENABLE都处理好了但JSON文件的键位坐标是错的导致VIA里按一个键高亮的却是另一个位置。这个问题没有捷径只能对着PCB的矩阵图一个一个格子去对。4.3 编译并刷写确认via键位图存在后编译命令是qmk compile -kb 你的键盘名 -km via如果是自己新建的非官方键盘目录命令变成qmk compile -kb 你的键盘名 -km via编译完成后会生成一个.hex或.bin文件路径在qmk_firmware/.build/下。刷写前先确认键盘进入bootloader模式再执行qmk flash -kb 你的键盘名 -km viaqmk flash会自动找bootloader并烧录比手动拖文件省事得多。烧录完成后键盘会自动重启此时系统会重新枚举USB设备——这里就是VID/PID第一次生效的时刻。如果这一步系统识别出来的设备名和你预期的不一样说明VID/PID配置没生效回到第3节重新检查。4.4 在VIA软件里加载设备打开VIA软件从官网下载正常情况下会自动识别键盘并显示在左侧设备列表里。如果没识别大概率是键盘没在VIA的在线仓库里。这时候需要在VIA主界面点“设置”Settings勾选“显示未定义键盘”Show undefined keyboards回到主界面左侧会多出一个“未识别设备”点击它然后选择“加载JSON定义文件”Load JSON definition file选择你准备好的JSON文件加载成功后界面上应该会出现你的键盘布局图键位可以正常拖拽修改。这里有个细节如果VIA软件版本比较老可能不支持新版QMK生成的JSON格式。新版QMK可能会生成device_version: 1.0.0等字段老版本VIA无法识别。遇到这种情况要么升级VIA到最新版要么把JSON文件里的新字段删掉保留最基础的字段。5. 刷进去之后VIA不识别问题排查与调试这一节是全文最有价值的部分——硬件坑、软件坑、系统坑我全踩过一轮整理出的这条排查链路能帮你把80%的“VIA不识别”问题定位出来。5.1 第一嫌疑VID/PID和JSON文件不匹配排查方法打开设备管理器Windows或系统信息macOS查看键盘设备的硬件ID把它们和JSON文件里的VID/PID做对比。Windows下查看硬件ID的路径右键“此电脑” → “管理” → “设备管理器”找到“键盘”或“人体学输入设备”下的设备右键 → “属性” → “详细信息” → 属性下拉框选“硬件ID”你会看到类似VID_FEEDPID_6060的字样。这串字符就是设备上报的VID/PID。如果它和JSON文件不一致那问题就在固件配置没生效。为什么会出现不一致最常见的原因是改了info.json但没重新编译或者编译时用了缓存的旧配置。QMK编译系统偶尔会残留旧的构建缓存改完配置后建议先执行qmk clean qmk compile -kb 你的键盘名 -km via5.2 Windows的USB驱动缓存一个很隐蔽的坑修改VID/PID之后Windows有时会记住旧设备的驱动状态导致新设备被错误地套用旧驱动。表现是插上键盘系统能识别出HID设备但VIA就是找不到。这种情况最简单的处理办法拔掉键盘打开设备管理器菜单栏“查看” → “显示隐藏的设备”展开“键盘”和“人体学输入设备”把所有灰色半透明的设备全部卸载特别注意那些名称里带“HID Keyboard Device”的重新插上键盘这样做是强制Windows重新枚举USB设备并把旧的驱动缓存清理掉。实测下来这个操作能解决七成以上的“VID/PID看起来对但VIA就是找不到”的问题。Linux下也有类似问题但没那么严重。如果你在Linux下刷完固件后VIA不识别多半是因为没有重启设备或没有重新插拔执行lsusb看看设备是否在列表里驱动问题其实很少见。5.3 键位矩阵过大VIA的硬限制如果你用的是配列比较大的键盘比如96配列、全尺寸104/108配列要特别小心。VIA对矩阵列数cols和单层非编码键位数量有硬编码限制。老版VIA的限制是最多16列如果你的PCB矩阵列数超过16即便固件编译通过VIA也无法正确读取键位表表现就是不识别或加载后布局错乱。如果你的矩阵超过限制有几个方向改用VialVial的限制更宽松但对固件体积要求更高。自定义VIA固件手动修改VIA库中的限制宏定义重新编译。这个操作比较复杂适合有编程基础的玩家。换主控如果PCB矩阵实在太大直接用支持更好的主控芯片。5.4 用Raw HID调试确认固件和软件“握手”成功这是排查VIA问题时比较高级的手段但很有效。Linux和macOS下可以用工具直接测试Raw HID通信。在Linux下一个简单的方法是sudo cat /dev/hidraw*插拔键盘时观察输出。如果能看到数据流输出说明Raw HID通道建立正常。Windows下可以用QMK官方的HID工具在qmk_firmware/util/目录里有一些调试脚本。不过对于大多数用户来说第5.1和5.2基本能解决90%的问题。到了Raw HID调试这一步说明已经很底层了一般是在做自制固件深度开发时才需要。5.5 一个排查表格现象优先检查项处理方式VIA软件里完全没有设备设备管理器里是否有未知设备检查VID/PID是否合法重刷驱动缓存能识别设备但加载JSON后布局错乱JSON文件键位坐标、矩阵行列数对照PCB矩阵图重写JSON设备设备亮了但改键无反应键盘是否重启过、VIA版本兼容性重新插拔键盘、升级VIA软件改键保存后重启丢失EEPROM空间不足或模拟EEPROM配置检查Flash空间调整固件大小只有部分键位可改键盘存在多个矩阵分区在JSON里分别定义各个分区5.6 别忘了清理旧驱动Windows系统有时会记住设备的“上次状态”包括键盘的布局信息。如果你之前给键盘刷过其他固件比如原始的出厂固件、Siri的改键固件Windows会缓存旧设备的HID描述符。这时候即使你刷了VIA固件系统可能还按旧设备的逻辑来响应导致VIA软件收到的设备信息不对。解决方法是重新插拔键盘或者进入设备管理器手动卸载设备并扫描硬件改动。USB HUB比较多的用户建议直接换个USB口插。6. 进阶建议从“能识别”到“好用”VIA能识别只是第一步。实际用下来要让VIA发挥全部价值还有很多细节值得关注。6.1 去VIA仓库提交键盘定义让全世界的VIA用户都能用如果你的键盘是自制的或者你在某个开源键盘固件基础上做了比较多的改动可以考虑把你的键盘定义提交到VIA的官方仓库。这样别人用VIA时插上你的键盘就能直接识别不需要手动导入JSON文件。提交的流程大致是Fork VIA的键盘定义仓库 这里泛指其定义库并非特指某个必须访问的地址在src/目录下按格式添加你的键盘定义文件提交Pull Request等维护者审核具体要求在仓库的README里有包括文件命名、字段格式、VID/PID唯一性等。提交前建议先检查一下你的VID/PID是否和现有定义冲突。6.2 JSON文件的管理与备份JSON文件是你键盘的“身份档案”丢了重做会很麻烦。建议把JSON文件和固件bin/hex文件放在同一个目录下保存用版本号命名如mykeyboard_v1.0.json在固件源码仓库里也保留一份JSON文件的副本6.3 VIA覆盖不了的固件设置VIA能调键位、灯效、宏但有些东西它管不了只能在固件里改。比如键盘的矩阵逻辑哪些物理按键对应哪些矩阵位置层的总数VIA最多显示QMK的4层超过就得改固件宏的字节数限制、每个层最多支持的编码键数量某些特殊的硬件配置比如旋钮编码器的行为、OLED屏的显示内容VS Code风格的玩法是先用VIA调日常设置再用固件做深度定制。我自己的方案是常用键位用VIA调整出厂默认层在固件里写好这样既灵活又稳妥。6.4 从VIA再往前一步Vial和REMAP如果你觉得VIA还不够好用可以试试Vial——它支持更细粒度的运行时调试比如看按键状态、调灵敏度等。Vial其实是VIA的分支它用了完全不同的通信协议固件侧要启用VIAL_ENABLE而不是VIA_ENABLE两者不兼容。另外如果只是想改键位不想装独立软件可以试试QMK的官方在线配置方式QMK Configurator不过它改完还需重新编译刷写和VIA完全是两回事。我从VIA切到Vial又切回VIA的经历是日常用VIA完全够了Vial的调试功能虽然多但对大多数用户是过度的。除非你需要调试键盘的矩阵问题否则别折腾。6.5 最后分享一点个人经验给键盘加VIA本质是在“定义键盘的身份”折腾了很多键盘之后我最大的体会是加VIA支持这件事表面上是在改代码、改配置实际上是在给键盘做“身份定义”。VID/PID是它在USB世界里的身份证JSON文件是它在VIA世界里的名片固件是它在物理世界的灵魂。这三者必须协调一致缺一不可。很多人在加VIA时卡住原因不是技术难度而是把这三个层面混为一谈了——只改了固件忘了改JSON只改了JSON忘了VID/PIDVID/PID都改了Windows驱动缓存又跳出来捣乱。这篇文章把这条链路完整梳理了一遍相信你再遇到不识别的情况能少走很多弯路。