STM32C5 NUCLEO 板 USB‑CDC 虚拟串口移植问题总览

1. 文档背景与业务问题现象

LAT1720 属于 ST 中国本地 Local Application Tips 技术笔记。STM32C5 的 MCU HAL2.0.0 软件包内，USBX 设备 CDC‑ACM 虚拟串口 FreeRTOS 示例工程device_cdc_acm_uart_freertos仅原生适配 NUCLEO‑C562RE（MB2213）开发板，没有提供 NUCLEO‑C5A3ZG（MB2310）版本示例。

客户硬件使用 STM32C5A3RGT6 芯片，直接将 NUCLEO‑C562RE 编译输出 hex 固件下载至 NUCLEO‑C5A3ZG 开发板，硬件 USB Type‑C 线缆连接 PC，Windows 系统弹出提示无法识别的 USB 设备。开发者主观认为同属 STM32C5 系列 NUCLEO 开发板硬件兼容，直接复用示例固件即可运行，实际出现 USB 枚举完全失败，没有生成虚拟 COM 端口。

现象还原：USB 硬件电路完全一致，硬件接线无误；固件编译无报错；下载完成设备上电，PC 操作系统 USB 栈识别失败，无 COM 设备生成。

资料获取：实战经验 | LAT1720 从NUCLEO-C562RE向NUCLEO-C5A3ZG移植USB示例

2. 板卡硬件基础信息与触发条件

板卡硬件信息

两块开发板 USB 外围保护、ESD、Type‑C 接口电路原理图完全一致，故障根因不在 USB 硬件外设，来自外部高速晶振 HSE 频率差异，连锁影响 USB 模块所需要的 48MHz CK48 时钟。

触发条件

1. 直接复用 NUCLEO‑C562RE 的 USBX CDC‑ACM FreeRTOS 示例工程；
2. 仅修改工程内部 MCU 器件型号为 C5A3ZG，没有同步修改 HSE 与 PSI 时钟相关软件配置；
3. 固件下载至 NUCLEO‑C5A3ZG 板卡运行；
4. USB 设备进行上电枚举。

3. 故障带来的业务影响

该故障无编译报错，属于隐性时钟配置错误，会带来多层级项目风险：

1. 产品调试阻滞：USB 虚拟串口是设备调试、日志输出、上位机交互的常用通道，USB 枚举失败，整机调试链路直接断开；
2. 排错方向误导：两块板 USB 原理图完全相同，工程师优先排查 USB 硬件、线缆、连接器、USBPHY 配置，忽略外部晶振差异，拉长排错周期；
3. 衍生时钟风险：HSE_VALUE 全局宏错误，会造成 HAL 库内部全部时钟计算错误，不单 USB 异常，系统主频、外设定时器、通信接口时序都会出现潜在异常；
4. 产品移植通用性误区：同 MCU 系列不同 NUCLEO 开发板，不能默认晶振参数兼容，直接复制示例工程极易踩坑。

4. 文档工具与参考资料矩阵