键盘二极管方向：COL2ROW 与 ROW2COL 极性指南

二极管方向是键盘矩阵设计中的关键部分。二极管装反可能导致按键无法触发、造成看似整个矩阵失效，或在排查故障时出现令人困惑的电压读数。

最重要的一点是：COL2ROW 和 ROW2COL 同时描述二极管方向与矩阵扫描安排。不能简单地把它们理解为信号或电流始终必须流动的方向。

对于标准 QMK 风格的矩阵，正确的二极管方向取决于矩阵哪一侧被扫描、哪一侧被读取。QMK 将 COL2ROW 定义为二极管阴极标记朝向行侧的配置，而 ROW2COL 则反转二极管方向。QMK 的标准矩阵代码也区分 COL2ROW 的读取列和 ROW2COL 的读取行操作。

这一点很重要，因为让列线为低电平并读取行线的设计，与让行线为低电平并读取列线的设计，需要相反的二极管极性。

本指南将逐步解释其中的电气关系，让你能够根据实际电路核对二极管方向，而不是只凭名称猜测。

本指南内容

1. 键盘矩阵如何使用二极管
2. 识别阳极和阴极
3. COL2ROW：正确的二极管方向与扫描逻辑
4. ROW2COL：正确的二极管方向与扫描逻辑
5. 最常见的混淆来源
6. PCB 封装与原理图设计
7. 测试与故障排查
8. 实用设计检查清单

---

键盘矩阵如何使用二极管

键盘矩阵可以减少扫描大量开关所需的 MCU GPIO 引脚数量。矩阵不会为每个按键连接一个独立输入，而是将开关布置在行与列的交点上。

典型矩阵包含：

• 行走线
• 列走线
• 机械或电气开关
• 在标准防鬼键设计中，每个矩阵开关对应一个二极管
• 连接到行、列线路的 MCU GPIO 引脚
• 选择矩阵一侧并读取另一侧的固件

二极管提供单向隔离。没有适当的隔离时，电流可能经由多个同时按下的开关流动，形成称为**鬼键（ghosting）**的非预期电气路径。

因此，二极管的作用不只是提示 PCB 上的安装朝向。它的极性必须与矩阵扫描器采用的电气方向一致。

正向偏置与反向偏置

当阳极电势足够高于阴极时，普通二极管会导通。

• **正向偏置：**电流可以从阳极流向阴极。
• **反向偏置：**二极管会大幅阻断从阴极流向阳极的电流。

对于键盘矩阵，真正应该问的是：

选中的矩阵线路被驱动且按键按下时，二极管能否从驱动侧向检测侧导通？

这个问题比试图从 COL2ROW 或 ROW2COL 这两个词推断答案更可靠。

二极管为何能防止鬼键

设想一个同时按下多个按键的矩阵。如果只有开关而没有单向隔离，已按下的按键可能在不同的行、列之间形成非预期路径。

在每个开关交点加入二极管，就能限制电流方向。这样可以阻断许多不需要的路径，并让固件判断实际处于激活状态的开关交点。

QMK 的矩阵文档描述了同一原理：二极管放置在开关之后、矩阵线路之前，使电流只能沿一个方向流动。QMK 文档中的 COL2ROW 示例将二极管的黑色标记放在行侧。

---

如何识别二极管的阳极和阴极

在判断某个二极管应属于 COL2ROW 还是 ROW2COL 电路之前，必须先正确识别其物理极性。

直插式 1N4148

对于 DO-35 封装的常见玻璃 1N4148：

• 黑色环带表示阴极。
• 另一端引脚是阳极。

安装元件时，环带是最实用的物理参照。引脚被剪短或折弯后，不应再把引脚长度作为永久的极性依据。

SMD 1N4148W 及相似器件

对于 1N4148W 这类常见 SMD 开关二极管，制造商会在封装上标出阴极。具体标记外观取决于制造商和封装类型。

例如，Diodes Incorporated 的 1N4148W 是 SOD-123 开关二极管，并规定使用阴极环带。生产中使用具体料号和封装时，务必核对该制造商的准确数据手册。

不要假定所有外观相似的二极管封装都采用完全相同的标记方式。

BAV70 双二极管

标准 SOT-23 版本的 BAV70 是带公共阴极的双开关二极管。对于 Nexperia BAV70 的引脚定义：

• 引脚 1 = 二极管 1 的阳极
• 引脚 2 = 二极管 2 的阳极
• 引脚 3 = 公共阴极

其他制造商可能使用不同的封装变体或引脚配置，因此在创建 PCB 封装前必须核对准确的数据手册。

这是对常见错误的重要纠正：不要假定所有三引脚双二极管都有相同的引脚定义。

用万用表核对

如果封装标记不清楚，可以使用万用表的二极管测试功能。

普通硅开关二极管在以下连接方式下通常会显示正向压降：

• 红表笔 → 阳极
• 黑表笔 → 阴极

交换表笔后，万用表通常应显示开路或过载状态。

准确的正向压降取决于二极管和测试电流，因此这项测试的主要用途是识别极性，而不是验证某个特定电压值。

---

COL2ROW：正确的二极管方向与扫描逻辑

QMK 将 COL2ROW 定义为：二极管的黑色标记（即阴极标记）朝向行侧，并位于开关与行线之间的矩阵配置。QMK 还提供了 COL2ROW 专用的矩阵读取函数 matrix_read_cols_on_row()。

硬件规则

COL2ROW：阴极 → 行

因此：

• 阳极 → 开关/列侧
• 阴极 → 行侧

二极管的物理标记朝向行。

典型电气路径

在常见的低电平有效解释中：

列侧
    |
  开关
    |
  阳极
    |
  二极管
    |
  阴极
    |
 行侧

当选定的矩阵配置提供有效的正向偏置路径时，电流必须按以下方向流动：

列 → 开关 → 二极管 → 行

GPIO 的空闲、有效、上拉、下拉和极性行为取决于固件。关键的硬件关系是：二极管从列侧向行侧导通。

QMK 配置

QMK 配置可以写成：

#define DIODE_DIRECTION COL2ROW

在较新的 keyboard.json 配置中，对应设置为：

{
    "diode_direction": "COL2ROW"
}

QMK 将 COL2ROW 和 ROW2COL 记录为传统二极管矩阵支持的两个方向设置。

关于“列到行”的重要说明

不要把 COL2ROW 这个名称当作 MCU 始终将列线驱动为低电平的普遍结论。

更好的记忆方式是：

COL2ROW
阴极 → 行

然后核对固件实际采用的扫描行为。

QMK 自己的文档用“二极管标记朝向行”描述 COL2ROW，而低层矩阵 API 则将该配置描述为基于行读取列。

---

ROW2COL：正确的二极管方向与扫描逻辑

与 COL2ROW 相比，ROW2COL 将二极管方向反转。

硬件规则

ROW2COL：阴极 → 列

因此：

• 阳极 → 行侧
• 阴极 → 列侧

二极管的物理标记朝向列。

典型电气路径

行侧
    |
  开关
    |
  阳极
    |
  二极管
    |
  阴极
    |
列侧

因此正向电流方向为：

行 → 二极管 → 开关 → 列

根据绘图约定，原理图中的开关与二极管顺序可能有不同表示，但电气极性必须保持一致。

QMK 配置

在 config.h 中：

#define DIODE_DIRECTION ROW2COL

或在 keyboard.json 中：

{
    "diode_direction": "ROW2COL"
}

QMK 矩阵 API 将对应的读取操作标识为 matrix_read_rows_on_col()，清楚说明了选定列与被读取行之间的关系。

何时适合使用 ROW2COL

以下情况可以采用 ROW2COL：

• 现有键盘硬件已经使用这一方向。
• 采用反向二极管方向可以显著简化 PCB 布线。
• 固件已经按 ROW2COL 设计。
• 自定义矩阵实现要求这种电气方向。
• 维护既有键盘设计，必须保持其硬件接口。

没有哪一种二极管方向在电气上天然优于另一种。固件和硬件必须相互匹配。

---

最常见的混淆来源：究竟哪一侧被驱动？

排查键盘矩阵时，这是最重要的一节。

人们经常误解 COL2ROW 和 ROW2COL，因为有时会把它们仅仅理解成 GPIO 信号传播的方向。

正确做法是通过三个问题确定电路：

1. MCU 正在驱动哪一侧？
2. MCU 正在读取哪一侧？
3. 二极管沿哪个方向导通？

情况 A：驱动列，读取行

假设电路有意设计为：

列 = 驱动输出
行 = 输入

并且选中的列被驱动为低电平。

如果行输入带上拉：

3.3 V
  |
行上拉
  |
行输入
  |
二极管
  |
开关
  |
列输出
  |
低电平

按下按键后，若要把行电压拉低，二极管必须从行向列导通。

因此：

阳极   → 行
阴极   → 列

这就是 ROW2COL 二极管方向。

所以，如果你把列驱动为低电平、按下开关，却仍在行输入测得约 3.3 V，一个可能的解释是：二极管按 COL2ROW 方向安装而处于反向偏置。

这正是 SPICE 模型看似与简化二极管方向说明矛盾的原因：模型遵循实际电气极性，而不是矩阵配置名称。

情况 B：驱动行，读取列

现在反转扫描安排：

行 = 驱动输出
列 = 输入

如果行被驱动为低电平，而列输入通过上拉保持高电平：

3.3 V
  |
列上拉
  |
列输入
  |
二极管
  |
开关
  |
行输出
  |
低电平

二极管必须从列向行导通。

因此：

阳极   → 列
阴极   → 行

这就是 COL2ROW 二极管方向。

正确的对照

矩阵配置	驱动侧	读取侧	二极管阳极	二极管阴极
COL2ROW	行	列	列侧	行侧
ROW2COL	列	行	行侧	列侧

这是理解两者关系最稳妥的表格。

不过，不要假设所有自定义键盘扫描器都使用完全相同的低电平有效安排。QMK 支持自定义矩阵扫描，自定义实现可能改变 GPIO 的控制方式。因此，只要设计没有使用标准矩阵扫描器，就应核对实际固件。

为什么行线可能保持 3.3 V

如果：

行 = 通过上拉保持 3.3 V
列 = 0 V

且二极管方向为：

阴极 → 行
阳极 → 列

那么：

行 = 3.3 V
列 = 0 V

会使二极管处于反向偏置。

二极管不会提供预期的行到列通路。

因此，按下开关也不一定会把行输入拉低。

这不是神秘的 MCU 故障，而是二极管极性所预示的结果。

---

PCB 封装与原理图设计：清晰标注二极管方向

即使电气设计正确，如果封装没有明确传达极性，PCB 组装仍可能失败。

原理图符号

使用可信 CAD 库中的标准二极管符号，并核对其引脚名称。

原理图符号应清楚区分：

• 阳极
• 阴极
• 阴极横线

不要把二极管符号描述为“箭头”。阴极由横线表示，二极管符号本身不是箭头。实物封装标记必须与原理图中的阴极对应。

PCB 封装标记

每个二极管封装都应使用清晰的阴极标识。

可采用的方法包括：

• 与阴极对齐的丝印横线
• 明确标出的阴极焊盘
• 装配图中的极性指示
• 整块板统一的元件方向
• 在适用时标出 1 号引脚或焊盘参考

不要把普通三角形或含义不明确的图形作为唯一极性标识。

保持方向一致

如果 PCB 条件允许，应让所有键盘二极管保持一致方向。

例如，COL2ROW 设计可以采用：

所有阴极 → 行

ROW2COL 设计则可以采用：

所有阴极 → 列

统一放置方向能显著简化 AOI 检查、人工目检和故障排查。

让封装匹配实际器件

必须根据准确的器件制造商和封装核对 PCB 封装。

以下器件尤其需要注意：

• SOD-123
• SOD-323
• SOD-523
• SOT-23
• 其他双二极管封装

仅凭封装名称不能保证不同器件拥有相同的引脚分配或相同的标记方式。

装配文件

装配图应清楚标出二极管极性。

对于量产 PCBA，制造资料最好包括：

• Gerber 文件
• 贴片坐标数据
• BOM
• 装配图
• 极性信息
• 特殊方向说明

原理图、PCB、BOM 和装配图中的极性，都应描述同一个物理方向。这正是SMT组装产线用来设定键盘PCB二极管方向的资料包。

---

键盘二极管方向的测试与故障排查

二极管方向问题通常可以通过目检、二极管测试、电压测量和固件核对组合定位。

目检

给板子上电前：

1. 找到实际二极管上的阴极标记。
2. 将它与 PCB 封装标记对照。
3. 确认所有二极管都遵循预期的矩阵方向。
4. 确认没有二极管旋转 180 度安装。
5. 确认器件封装与 BOM 一致。

检查 SMD 器件时通常需要放大观察。

单个二极管测试

怀疑某个二极管时：

1. 断开电源。
2. 如果在路测量结果含糊，将二极管从电路中隔离。
3. 将万用表设为二极管测试模式。
4. 将红表笔接到预期的阳极。
5. 将黑表笔接到预期的阴极。
6. 确认正向导通。
7. 交换表笔并确认反向截止。

在路测量可能受到其他元件和矩阵路径影响，因此可疑结果应在二极管隔离后再次确认。

矩阵电压测试

对于：

列 = 低电平输出
行 = 带上拉的输入

测量行电压：

• 松开按键 → 行线可能通过上拉保持高电平。
• 按下按键且二极管为正确的 ROW2COL 极性 → 行线应被拉向选中的低电平列线，但具体结果取决于 GPIO 配置和二极管压降。
• 按下按键但二极管极性相反 → 行线可能保持高电平，因为二极管处于反向偏置。

在排查 SPICE 仿真或原型板时，这项测试尤其有用。

固件核对

检查固件设置。

对于 QMK：

#define DIODE_DIRECTION COL2ROW

或：

#define DIODE_DIRECTION ROW2COL

对于 keyboard.json：

"diode_direction": "COL2ROW"

或：

"diode_direction": "ROW2COL"

该设置必须与物理矩阵设计一致。

QMK 也支持自定义矩阵实现。如果键盘使用自定义扫描器，在核对自定义代码前，不要假定它遵循标准矩阵行为。

常见故障模式

所有按键都失效

可能原因包括：

• 固件二极管方向与硬件不匹配。
• 矩阵 GPIO 配置错误。
• 公共行线或列线断路。
• 扫描器配置了错误的矩阵尺寸。

单个按键失效

可能原因包括：

• 二极管装反
• 焊接缺陷
• 走线断路
• 开关损坏
• 器件错误

某一行或某一列失效

可能原因包括：

• 行线或列线断裂
• 连接器或焊点不良
• MCU 引脚分配错误
• 短路
• 矩阵配置错误

列被驱动为低电平时，行仍接近 3.3 V

首先确认：

• 行线确实有上拉。
• 列线确实已配置并驱动为低电平。
• 开关在电气上确实闭合。
• 二极管极性允许电流从行流向列。
• 固件采用预期的 ROW2COL 风格扫描关系。

出现多按键鬼键

检查：

• 是否缺少二极管
• 二极管方向是否错误
• 矩阵布线是否错误
• 固件矩阵配置
• 是否存在自定义矩阵逻辑

---

键盘二极管方向设计检查清单

在发布键盘 PCB 进行制造或组装前，确认以下各项。

电气设计

• 明确矩阵是 COL2ROW 还是 ROW2COL。
• 确定扫描期间哪一侧被驱动。
• 确定 MCU 读取哪一侧。
• 确认按键按下时预期的电流路径。
• 确认每个二极管在按键按下的预期状态下正向偏置。
• 确认二极管方向能够阻止不需要的反向路径。

原理图

• 核对二极管阴极符号。
• 核对阳极和阴极网络名称。
• 确认开关和二极管连接到预期的矩阵线路。
• 确认原理图与固件配置一致。
• 避免使用含义不明确的极性符号。

PCB 布局

• 核对每个二极管封装的极性。
• 添加清晰的阴极标记。
• 尽可能保持二极管方向一致。
• 检查准确的制造商封装图。
• 确认元件本体不会遮挡 PCB 丝印。

固件

• 核对 DIODE_DIRECTION。
• 核对 matrix_pins.cols。
• 核对 matrix_pins.rows。
• 确认固件扫描方向与实际二极管方向一致。
• 在假定采用标准行为前，检查是否使用自定义矩阵扫描。

制造

• 核对 BOM 料号。
• 核对封装。
• 核对装配图中的阴极标记。
• 核对贴片坐标旋转角度。
• 贴装后检查二极管极性。
• 执行 AOI。
• 对已组装板进行矩阵电气测试。

---

COL2ROW 与 ROW2COL 快速参考

下面的摘要最适合随 PCB 设计资料一起保存：

项目	COL2ROW	ROW2COL
阴极	行	列
阳极	列	行
QMK 方向设置	COL2ROW	ROW2COL
QMK 标准读取函数	matrix_read_cols_on_row()	matrix_read_rows_on_col()
典型硬件电流路径	列 → 开关 → 二极管 → 行	行 → 二极管 → 开关 → 列
如果设计驱动列为低电平并读取行	不匹配的标准方向	匹配方向
如果设计驱动行为低电平并读取列	匹配方向	不匹配的标准方向

关键规则很简单：

不要只根据“列”和“行”这两个词选择二极管方向。要确定矩阵哪一侧被驱动、哪一侧被检测，以及按键按下时二极管是否处于正向偏置。

按照 QMK 的标准定义，COL2ROW 表示阴极标记朝向行，而 ROW2COL 将其反转。QMK 还为这两种配置分别记录了读取行和读取列的矩阵函数。

---

HILPCB 键盘 PCB 组装

正确的二极管极性是可靠键盘 PCBA 生产的重要组成部分。面向生产的键盘组装流程应核对器件料号、封装、贴装旋转角度、阴极标记和矩阵功能。

HILPCB 提供键盘 PCB 组装和 SMT 生产，流程可包括：

• BOM 与器件核验
• 贴片程序编制
• SMT 组装
• 自动光学检测（AOI）
• 电气测试
• 原型及小批量组装
• 批量生产

对于键盘 PCB 项目，制造资料应明确规定二极管料号、封装、极性和组装方向。

---

最终要点

确定键盘二极管方向最稳妥的方法，是从实际的电气扫描电路反向推导。

如果设计为：

列 = 低电平驱动
行 = 带上拉的输入

二极管必须按以下方向导通：

行 → 列

因此：

阳极   → 行
阴极   → 列

在标准 QMK 术语中，这对应 ROW2COL。

如果设计为：

行 = 低电平驱动
列 = 带上拉的输入

二极管必须按以下方向导通：

列 → 行

因此：

阳极   → 列
阴极   → 行

这对应 COL2ROW。

所以，当列被驱动为低电平而行输入仍接近 3.3 V 时，如果硬件使用 COL2ROW 极性、但扫描程序期待相反方向，那么二极管反向偏置就可能是正常原因。

始终核对实际固件扫描实现，尤其是使用自定义矩阵扫描器时，因为 GPIO 被驱动还是被读取，最终由固件的电气行为决定，而不是由配置名称单独决定。

Related links

• SMT组装