基于TinyUSB的STM32 U盘实现：从RAM Disk到SPI Flash完整教程

做USB开发之前，我一直觉得这是嵌入式里最劝退的方向之一。协议规范几百页，描述符里错一个字节可能就枚举失败，调试工具又贵又难上手。直到后来用了TinyUSB，我才发现实现一个标准USB设备并没有想象中那么可怕。拿最近同事问得最多的例子来聊：用TinyUSB在STM32上做一个U盘。核心代码量很少，环境顺的话五分钟跑通真不是吹牛，踩坑点也高度集中，完全有套路可循。

这篇文章我基于最常用的STM32F103C8T6开发板来演示，用的是内部RAM模拟U盘，再进阶到外挂W25Q128 Flash实现掉电保存。无论你是做毕业设计、做数据采集存储，还是想把手头的板子变成移动存储工具，这套流程都可以直接照着搬。顺便会把我在实际调试中遇到的不识别、无盘符、读写报错这几个经典问题一起拆掉。

1. 先说清楚：为什么是TinyUSB，为什么要拿STM32做U盘

1.1 USB驱动开发让人崩溃的地方

很多人一提到USB开发就头大，这种头大不是没道理的。USB协议栈从物理层、传输层到协议层、类层，层层叠叠，真要自己完整实现一遍，光是把《USB 2.0 Specification》啃明白就得花掉不少精力。哪怕只做最简单的设备，也要操心设备描述符、配置描述符、字符串描述符怎么填，端点怎么分配，控制传输的状态机怎么走，枚举过程中主机发来标准请求怎么回复。一套折腾下来，很多人还没看到U盘盘符，就先放弃了。

更痛苦的还在后头：设备的枚举只是第一步，真正跑起来之后，批量传输的Buffer怎么管理、传输错误怎么重试、Class-specific请求怎么处理，这些全是经验活。就算你用STM32官方USB库，它那一套回调加状态机的设计，历史包袱也重，配置繁琐，遇到问题排查起来并不轻松。所以，如果你只是想快速实现一个能用的USB设备，从零写协议栈，或者硬啃厂商中间件，性价比都很低。

1.2 TinyUSB到底解决了什么问题

TinyUSB是Adafruit发起维护的开源USB协议栈，现在很多主流芯片的开发环境里都在用，比如RP2040的Pico SDK、ESP32-S系列，底层都集成了TinyUSB。它最大的特点是：不绑定某个特定芯片厂家的SDK，通过一套统一的移植层适配不同硬件，同时对CDC、HID、MSC、MIDI、UAC这些常见设备类做了完整支持。你不需要理解USB规范里的每个字节，只需要按它约定的回调函数把数据搬进来、搬出去就行。

对比一下传统的开发方式就更直观。用STM32官方USB中间件，配置描述符、处理各种请求回调都要自己来，而且每个系列芯片的库风格还有差异。TinyUSB则是一套代码通吃，你换芯片平台，应用层代码基本不用动。它还自带了不少示例工程，最合适拿来当起点改。授权也很友好，MIT协议，商用项目用着没有顾虑。就我实际使用感受来说，TinyUSB最厉害的地方是把协议栈里最复杂的枚举、标准请求、Class协议解析都封装掉了，留给你的接口非常清爽。

1.3 选择MSC类USB存储设备的理由

在TinyUSB支持的各种设备类里，MSC（Mass Storage Class，大容量存储类）是最适合练手也最实用的方向之一。它的本质是把设备模拟成一个块设备，操作系统把它当成普通U盘来访问，不需要额外安装驱动，插入电脑就能看到盘符。开发流程相对简单，因为它只需要处理SCSI命令里的那么几个关键操作：查询设备、读取容量、读块、写块。

这个场景的实际价值很大。嵌入式产品需要把采集到的数据导出到电脑，或者需要从电脑拷贝配置文件、升级固件，USB U盘方式都是很自然的交互手段。很多基于STM32的毕业设计项目，比如数据记录仪、离线编程器、智能设备升级工具，核心存储模块用这套方案就够了。后面我会把RAM盘和Flash盘两种做法都走一遍，你按自己的需求选。

2. 硬件和开发环境：别在这些小事上翻车

2.1 一套能跑的硬件清单

硬件准备并不复杂。开发板用最常见的STM32F103C8T6最小系统板就行，就是那种网上二三十块钱一块的“蓝板”或者“黑板”，很多人手里都有，想验证代码完全够用。如果你用江科大入门教程那块STM32F103C8T6学习板，也可以直接拿来跑，PA11、PA12两个引脚自带USB座，省了飞线。

我做这件事用到的硬件清单是这样：

这里有个硬件上的关键点必须单独说：STM32F103C8T6的USB D+引脚（PA12）在外部需要接一个1.5kΩ上拉电阻到3.3V。很多开发板上已经集成了这个电阻，但如果是自己做的最小系统板，千万别漏掉，漏了电脑永远识别不到设备。D-（PA11）和D+（PA12）不能接反，接反了也会枚举失败。

2.2 Keil5环境：芯片包没装，一切都白搭

开发环境我以Keil MDK5为例，因为这是大多数人电脑上已经装了的工具。一个很常见的问题是：Keil MDK装好了，新建工程时却找不到STM32F103系列芯片，原因就是没装对应的芯片包。Keil5和过去的Keil4不一样，芯片支持是以后缀为.pack的芯片包形式提供的，需要单独安装。

具体做法是：打开Keil MDK，在菜单栏选Pack Installer，然后在Device列表里找到STMicroelectronics -> STM32F1 Series，点击Install。如果Pack Installer加载慢，也可以直接从Keil官网下载STM32F1系列的DFP安装包，双击安装。装完之后新建工程，你会发现芯片型号列表里已经能选STM32F103C8T6了。顺便提醒一句，STM32F103C8T6在Keil里显示为STM32F103C8，两个名字指的是同一个东西。

另外一个很多人会忽略的点：Keil5并不能直接兼容老的C51工程，如果平时还要写51单片机，需要单独装C51的编译器，并切换到对应的Toolchain。这和本文主题无关，但如果你在一台电脑上同时遇到“为什么选不了ST芯片”和“为什么选不了51芯片”，多半就是芯片包或者编译器安装不完整。环境问题虽然简单，但排查起来最浪费时间。

2.3 拿到TinyUSB源码：库目录怎么看

TinyUSB源码托管在GitHub上，仓库名就叫tinyusb，直接Download ZIP下载或者git clone都行。它的目录结构很清晰，核心就两个地方：src是协议栈本体，examples是官方示例。我们做MSC设备，直接看examples/device/msc这个目录就够了。它里面已经包含了main.c、tusb_config.h、usb_descriptors.c，还有一个用于演示存储介质的msc_disk.c。

第一次打开TinyUSB源码的人可能会被hw目录吓到，里面各种开发板的板级文件，看起来非常庞大。但实际上我们用到的东西很少，大多数情况下只需要拷贝src目录，再加一个针对自己芯片的port实现。对STM32F1来说，TinyUSB在src/portable/st/stm32_fsdev里已经把USB硬件驱动写好了，你不需要碰底层，只需要保证芯片时钟、GPIO配置正确，然后在主循环里调用协议栈的处理函数就行。

3. MSC设备栈的工作原理：四回调吃透U盘

3.1 TinyUSB设备栈的运行机制

先把TinyUSB设备栈的运行模型搞清楚，后面写代码才不会懵。整个模型可以理解成“一个总机加一堆分机”。总机就是协议栈核心，它负责处理USB总线上所有底层事务：枚举、标准请求、端点传输、错误处理。分机就是你写的应用层回调函数。主机发来一个请求，协议栈解析之后，按类型去调用对应的回调，你的代码只需要在那个回调里把数据准备好或者收下来。

代码层面只有两个函数要关注。第一是tusb_init()，上电时执行一次，完成硬件初始化和协议栈状态机初始化。第二是tud_task()，这个函数要放在主循环里反复调用，它相当于协议栈的心脏，所有USB中断事件都在它这里被处理。很多人第一次移植失败，就是因为main函数里只调了tusb_init()，忘了在while(1)里调tud_task()，结果设备插上电脑完全没反应。

这套设计对应用层非常友好。比如主机要读取U盘某个扇区，协议栈解析完READ(10)命令后，会调用你实现的tud_msc_read10_cb()回调，你只需要把对应扇区的数据拷贝到协议栈指定的缓冲区里，返回true，剩下的传输控制全部由TinyUSB完成。

3.2 CBW、CSW和SCSI命令：和主机打交道的基础

MSC设备在USB总线上和主机的通信模式是这样的：主机通过批量端点OUT发送一个31字节的CBW（Command Block Wrapper，命令块包装），里面包含了SCSI命令块；设备执行完命令后，通过批量端点IN回复一个13字节的CSW（Command Status Wrapper，状态包装），告诉主机命令执行成功还是失败。

这个过程你也可以在生活中找到类比。CBW就像你去食堂窗口递菜单，菜单上写明了想吃什么菜、要几份、送到哪张桌子。CSW就是窗口师傅做完菜之后喊一嗓子“做好了，来取”。SCSI命令则是菜单上的具体菜名。MSC类设备里标准SCSI命令很多，但实际经常用到的就那么几个：TEST UNIT READY（设备是否就绪）、INQUIRY（设备厂商和产品信息）、READ CAPACITY(10)（返回容量）、READ(10)（读扇区）、WRITE(10)（写扇区）。主机操作系统探测U盘时，会依次发这些命令，你的代码逐条响应，系统就能识别出“这是一个可用的磁盘”。

好消息是，TinyUSB已经把CBW、CSW的封装和解析都做完了，你根本不需要手动构造这些结构体。你要做的只是实现几个语义明确的回调：查询就绪、返回容量、读数据、写数据。协议栈负责把回调返回的数据打包成CSW，发送到主机。

3.3 存储介质怎么选：RAM盘先上手，Flash再进阶

TinyUSB的MSC层并不关心你的数据存在哪里，它只认“逻辑块地址（LBA）+偏移+长度”这一套存取模型。所以存储介质可以是内部RAM、外部SPI Flash、SD卡甚至自定义的加密存储设备，接口都是一样的。这就给开发带来了很大灵活性。

我建议你第一版先用RAM Disk验证，就是把一块全局数组当作磁盘。这么做的原因是：RAM访问速度快，读写逻辑简单，不涉及擦除和写对齐问题，适合先把USB枚举、主机识别这些流程跑通。等确认U盘功能正常了，再把RAM替换成Flash，存储介质变了，但USB侧的代码几乎不用改。

RAM Disk的缺点是掉电丢数据，只能作为调试手段。想做出真实的U盘效果，必须用非易失存储。STM32内部的Flash也可以用来存储，但一方面容量有限，另一方面需要处理Flash磨损均衡和擦写保护，反而比外挂一颗SPI Flash更麻烦。所以我后面进阶部分用最常见也最便宜的W25Q128来做，8MB容量，SPI接口，一颗芯片就能解决。

4. 5分钟跑通一个RAM Disk U盘：代码逐段拆

4.1 工程构建与文件组织

现在进入实操环节。我建议的工程组织方式是这样的：新建一个Keil工程，把TinyUSB的src目录整个加进来，然后从examples/device/msc里拷贝tusb_config.h、usb_descriptors.c、msc_disk.c、main.c这几个文件到自己的应用目录。这样改起来最快，因为官方示例已经把很多细节处理好了，我们只需要做裁剪。

如果你不想拷贝官方示例，也可以在freertos和device两个目录之外独立建一个应用层文件。更直接的方式是直接用官方示例目录里的board文件夹下的stm32f103各文件，那里面有现成的时钟和GPIO初始化。不过官方示例用的是GCC Makefile方式，在Keil里需要自己建立工程，手动添加源文件。操作上不算复杂，关键是别漏文件。src目录下所有.c文件都可以加进去，编译时没被调用的部分会被链接器丢弃，不影响最终体积。

main.c的基本逻辑很朴素：先初始化系统时钟、GPIO和USB硬件，然后调用tusb_init()，进入一个死循环，循环里调用tud_task()。有些示例里还会调用一些板级LED闪烁函数，那只是为了看板子活着，删掉不影响功能。

4.2 tusb_config.h：你想要的关键配置

tusb_config.h里集中了TinyUSB的编译期配置项。对MSC设备来说，下面几项是关键。

#ifndef TUSB_CONFIG_H_ #define TUSB_CONFIG_H_ // 指定TinyUSB运行在设备模式，全速设备 #define CFG_TUSB_RHPORT0_MODE (OPT_MODE_DEVICE | OPT_MODE_FULL_SPEED) // 设备支持的Class，启用MSC #define CFG_TUD_CDC 0 #define CFG_TUD_MSC 1 #define CFG_TUD_HID 0 #define CFG_TUD_MIDI 0 #define CFG_TUD_VENDOR 0 // MSC读写的内部缓冲区大小，必须>=一个逻辑块大小 #define CFG_TUD_MSC_BUFSIZE 512 #endif

CFG_TUSB_RHPORT0_MODE里的OPT_MODE_DEVICE表示设备模式，OPT_MODE_FULL_SPEED表示全速设备。STM32F1的USB外设是USB 2.0 Full Speed设备，只能选全速模式，不能选高速。CFG_TUD_MSC设为1启用MSC类，值为0的类会被裁掉，不编译对应的协议栈代码，节省Flash空间。CFG_TUD_MSC_BUFSIZE默认512就够了，因为后面存储介质的逻辑块大小我就按512字节来设计，SCSI读写最小单元就是512字节。

还有一个容易忽略的配置：设备端点缓冲区在哪里分配。TinyUSB默认用了自定义内存段宏，如果你用的是标准Keil工程，直接在tusb_config.h里加上#define CFG_TUSB_MEM_ALIGN __attribute__((aligned(4)))就行，保证缓冲区的4字节对齐，USB DMA传输时不会出奇怪问题。

4.3 描述符文件：VID/PID和端点分配

usb_descriptors.c负责生成设备描述符、配置描述符和字符串描述符。对MSC设备来说，最值得关注的是配置描述符里的接口描述符和端点描述符。MSC类接口必须包含两个批量端点：一个IN端点用于向主机发送数据，一个OUT端点用于接收主机数据。官方示例的配置描述符会定义接口类为0x08（MSC类），子类0x06（SCSI命令集），协议0x50（Bulk-Only Transport，即BBB传输协议）。

端点分配方面，F103的USB设备有固定的端点资源，PA11/PA12对应USB D-/D+，端点0用于控制传输，普通端点地址从0x01到0x0F。我习惯用0x81作为批量IN端点，0x01作为批量OUT端点，最大包长设置为64字节。

设备描述符里的VID和PID建议改成自己项目的唯一值。默认的VID是0xCafe，这是TinyUSB的测试VID，Windows下虽然能用，但如果同时插多个TinyUSB设备可能会冲突。量产产品需要向USB-IF申请VID，个人学习或者毕业设计直接用0xCafe也没问题。字符串描述符里可以写“TinyUSB STM32 Disk”这类产品名，Windows的资源管理器会显示这个名字。

4.4 核心回调：MSC设备灵魂四件套

这一步是整个工程最核心的部分。官方示例msc_disk.c里的回调函数，我抽出来逐段解读。下面是一份基于RAM Disk的完整实现，逻辑非常简单，但功能完整。

#include "tusb.h" #define BLOCK_SIZE 512 #define BLOCK_COUNT 32 // 16KB RAM Disk，适合F103的小内存 static uint8_t disk[BLOCK_SIZE * BLOCK_COUNT]; // 设备信息：厂商、产品、版本 void tud_msc_inquiry_cb(uint8_t lun, uint8_t vendor_id[8], uint8_t product_id[16], uint8_t product_rev[4]) { (void) lun; memcpy(vendor_id, "TinyUSB", 8); memcpy(product_id, "STM32 Disk", 16); memcpy(product_rev, "1.0", 4); } // 设备是否就绪 bool tud_msc_test_unit_ready_cb(uint8_t lun) { (void) lun; return true; } // 返回容量：逻辑块数量和每块字节数 void tud_msc_capacity_cb(uint8_t lun, uint32_t* block_count, uint32_t* block_size) { (void) lun; *block_count = BLOCK_COUNT; *block_size = BLOCK_SIZE; } // 读操作：把RAM中的数据拷贝给主机 bool tud_msc_read10_cb(uint8_t lun, uint32_t lba, uint32_t offset, void* buffer, uint32_t bufsize) { (void) lun; memcpy(buffer, disk + lba * BLOCK_SIZE + offset, bufsize); return true; } // 写操作：把主机发来的数据写入RAM bool tud_msc_write10_cb(uint8_t lun, uint32_t lba, uint32_t offset, uint8_t* buffer, uint32_t bufsize) { (void) lun; memcpy(disk + lba * BLOCK_SIZE + offset, buffer, bufsize); return true; } // 其他SCSI命令：这里统一返回0，表示不额外处理 int32_t tud_msc_scsi_cb(uint8_t lun, uint8_t const scsi_cmd[16], void* buffer, uint16_t bufsize) { (void) lun; (void) scsi_cmd; (void) buffer; (void) bufsize; return 0; } // 启动停止介质，比如弹出U盘 bool tud_msc_start_stop_cb(uint8_t lun, uint8_t power_condition, bool start, bool load_eject) { (void) lun; (void) power_condition; (void) start; (void) load_eject; return true; }

这段代码里有几个地方需要解释。tud_msc_capacity_cb里返回的block_count和block_size决定了Windows看到的是一个多大的磁盘。block_size固定512字节，这是大多数存储设备的逻辑块大小，block_count是总块数，两个相乘就是磁盘容量。我把RAM盘设为32块，总容量16KB，这个容量小到Windows资源管理器可能都不会显示可用的空间，但足够用来验证枚举和基本读写。如果你用的是F407这种大内存芯片，可以把BLOCK_COUNT调到128甚至更多，容量大一些，Windows更能接受。

tud_msc_read10_cb和tud_msc_write10_cb是实际读写函数。因为RAM可以按任意地址任意字节访问，所以逻辑就是一个memcpy。注意这里传入的lba是逻辑块地址，offset是块内偏移，bufsize是本次操作要搬运的字节数。主机一次READ(10)可能请求1个扇区，也可能请求多个扇区，所以地址计算要写成lba * BLOCK_SIZE + offset，而不是简单地lba * BLOCK_SIZE。

tud_msc_scsi_cb是用来兜底的。TinyUSB已经把INQUIRY、READ CAPACITY、READ、WRITE这些常用命令封装好了，但SCSI命令集很大，总有一些命令没有对应的专用回调，比如MODE SENSE(6)、START STOP UNIT，它们会走到这个回调里。返回0表示不处理，协议栈会返回错误状态给主机；如果你确信某个命令需要返回特定数据，也可以在这个回调里填充buffer并返回正数。对绝大多数应用来说，返回0就够了。

4.5 编译烧录与电脑侧验证

代码写完之后，在Keil里配置一下烧录器。Options for Target -> Debug页面选择ST-Link Debugger，然后进入Settings，在Flash Download里勾选Reset and Run，烧录完成之后板子自动复位运行。连接方式用SWD四线：SWDIO、SWCLK、GND、3.3V。

烧录完成，把USB线连接到开发板的USB口，另一端插电脑。这时设备管理器里应该出现“USB大容量存储设备”，磁盘管理里也能看到一块16KB左右的磁盘。由于容量太小，资源管理器可能不显示盘符，这是正常的，不代表设备没工作。想验证写入是否成功，有两种办法：一种是在磁盘管理里手动分配一个盘符，另一种是直接把BLOCK_COUNT调大，比如在F407上调到1024，做成512KB的RAM盘，这时候Windows会弹窗提示“需要格式化”。

如果弹窗了，格式化时选FAT32或exFAT都行。格式化的过程会执行一系列SCSI命令，包括MODE SENSE、WRITE、READ CAPACITY等，你的回调函数都会被真实调用到。格式化完成之后，往U盘里拖一个文件，再读出来，对比文件内容没变化，说明RAM Disk版U盘功能完全跑通了。这个过程就是整个方案的核心验证。

5. 从Demo到产品：把W25Q128变成真正的U盘

5.1 为什么要换掉RAM Disk

RAM Disk跑通之后，功能上已经实现了U盘，但它有一个致命问题：断电之后数据全部消失。真实的U盘产品必须使用非易失存储介质。换用外部SPI Flash之后，U盘的数据在掉电后依然能保留，这就让这个方案具备了实际产品的雏形。比如做个数据记录仪，把采集到的数据写到U盘里，拔下来插电脑上就能看，这才是MSC设备最有价值的应用方式。

W25Q128是我用得最多的SPI NOR Flash芯片，容量8MB（实际是128Mbit），毫秒级擦写，接口简单，市面上模块也很便宜。它虽然不是专门的U盘存储芯片，但作为嵌入式设备的导出存储已经完全够用。如果你的应用需要更大容量，也可以换成W25Q256（32MB）或者SD卡方案，接口逻辑类似。

5.2 W25Q128驱动：SPI读写的几个关键点

W25Q128的数据手册很薄，核心操作就几类命令：读ID（0x90）、写使能（0x06）、读数据（0x03）、扇区擦除（0x20，一次擦4KB）、页编程（0x02，一次最多写256字节）。SPI接口在STM32F103上我用SPI1，引脚分配是SCK=PA5、MISO=PA6、MOSI=PA7、CS=PA4，工作模式SPI Mode 0，时钟分频8分频。

初始化代码的要点是：先拉低CS，发送0x90命令读厂商ID和设备ID，确认Flash连接正常；然后把Flash设置为掉电模式解除，虽然W25Q128上电默认就处于活动状态，但养成习惯总没错。这一步如果返回值不对，后面所有读写都是空中楼阁。

读操作最简单，发送0x03命令后跟24位地址，然后连续读出任意字节。写操作就要小心了，W25Q128有两个硬性约束：写入之前必须先擦除，擦除粒度是4KB扇区；页编程单次最多写256字节，而且不能跨页边界。这意味着如果主机发来的写请求超过256字节，或者要写入到某个扇区的尾部且跨过页边界，驱动必须拆分处理。

5.3 回调改写：从内存搬运到Flash搬运

把RAM Disk的回调改成Flash版本，本质上是把memcpy替换成Flash读写函数，但有一点必须处理：W25Q128只支持按扇区擦除，不支持按512字节逻辑块擦除。如果主机每次写512字节，而Flash扇区是4KB，直接写之前必须先擦除整个4KB扇区，这会引来两个问题：一是经常做整扇区擦除会严重影响写入速度；二是如果主机写入的数据量小于4KB，不能简单把整个扇区擦掉，否则没被覆盖的数据就丢了。

我采用的是“先读后写再回写”的经典方案：在tud_msc_write10_cb里，根据lba计算出对应的Flash地址，如果本次写请求跨越了Flash扇区边界，就直接把涉及的4KB扇区读到RAM缓冲区，在缓冲区里修改对应字节，然后把整个4KB擦除并写回。如果本次写请求只落在同一个Flash扇区内，也按同样方式处理。这样做逻辑清晰，代码量小，缺点是有额外读写开销，但对我们这种低频率的数据导入导出场景完全够用。

bool tud_msc_write10_cb(uint8_t lun, uint32_t lba, uint32_t offset, uint8_t* buffer, uint32_t bufsize) { (void) lun; uint32_t flash_addr = lba * BLOCK_SIZE + offset; // 计算涉及哪些Flash扇区，每个扇区4KB // 读扇区内容，修改，擦除，写回 ... return true; }

实现细节我不展开写了，核心思路是设计一个w25qxx_write_sector辅助函数，传入Flash地址和数据长度，内部自动处理擦除、读回、页编程拆分这些事务。写完之后，再改动几个地方：tud_msc_capacity_cb里的block_count要改成Flash实际容量除512，比如W25Q128是8MB，block_count = 8 * 1024 * 1024 / 512。tud_msc_read10_cb里直接调用W25Q128读函数。

5.4 实测数据：格式化慢、写入快、要防掉电

flash版U盘第一次插入电脑，Windows同样会提示格式化，格式化为FAT32。格式化过程中Windows会进行大量写入操作，你会看到进度条走得比较慢，这是正常的，因为每次写之前都要做扇区擦除。格式化完成后，向盘里拷贝文件，速度取决于SPI频率和擦除策略，实测在18MHz SPI时钟下，连续写入大文件的平均速度大约在100~200KB/s这个量级，读取速度会快一些。

值得提醒的是，SPI Flash的等待状态和电源稳定性对写入可靠性影响很大。如果在写入过程中拔掉USB线，可能造成文件系统损坏，或者Flash某个扇区处于半擦除状态。产品化时建议增加电容储能掉电检测，或者把文件系统设计成只读挂载，需要写入时才切换。还有一点，W25Q128擦写寿命大约10万次，如果频繁擦写同一扇区，需要做磨损均衡，否则Flash会提前老化。

6. 联调翻车现场：不识别、没盘符、读写失败的排查手册

6.1 插上没任何反应：先检查时钟和上拉

电脑插上USB线之后完全没动静，设备管理器里也没有任何新设备出现，这是最常见的故障。我排查这个问题的顺序固定是三步：先换一根数据线排除线材问题，再量D+引脚的电平，最后检查时钟配置。很多人第一步就被劣质线材坑了，USB线只供电不同数据，你换了三块板子都一样，最后发现是线的问题，非常耽误时间。

D+的电平检查很有意义：设备上电后，如果USB逻辑正常，D+引脚会被1.5kΩ电阻拉高到3.3V左右，主机检测到这个电平跳变才认为有设备插入。如果量出来D+一直是低电平，说明上拉电阻没接，或者USB外设时钟没正常工作。STM32F103的USB外设必须由48MHz时钟驱动，这个时钟通常来自PLL输出分频。很多人的板子外部晶振不是8MHz，导致PLL倍频后无法得到48MHz，USB模块就没法工作。检查一下系统时钟树，确认USB时钟源正确配置为48MHz，这是STM32 USB开发里绕不过去的一关。

6.2 设备管理器有设备，我的电脑没盘符

设备管理器里能看到“USB大容量存储设备”，说明枚举成功，但“我的电脑”里找不到盘符。这个问题的排查优先级是：先看磁盘管理，再查容量回调，最后用工具看枚举细节。磁盘管理里如果能看到一块未格式化、未分配盘符的磁盘，手动右键分配盘符或格式化就行。

如果磁盘管理里磁盘容量显示为0，那基本可以确定是tud_msc_capacity_cb返回的容量不对。Windows会向设备发送READ CAPACITY命令获取容量，如果返回的block_count为0，系统就会认为介质无效，不分配盘符。另外检查一下tud_msc_test_unit_ready_cb是否一直返回false，这个回调如果返回false，主机也会认为介质未就绪，同样不会显示盘符。

还有一个不太容易想到的原因：VID/PID和电脑里已有的某个设备冲突，导致Windows的驱动缓存识别错误。这种情况换一个VID/PID重新烧录就能解决。

6.3 复制文件报错或盘符消失：排查SCSI和Flash

能识别盘符，但一复制文件就报“参数错误”或者“无法完成操作”，甚至整个盘符消失，这类问题更多出现在Flash版本里。首先检查你的回调函数有没有做长时间阻塞操作。TinyUSB的回调是在USB中断上下文里被调用的，不是你可以随意阻塞的地方。如果tud_msc_write10_cb里做了Flash擦除这种毫秒级操作，时钟中断和USB传输时序就会被破坏，最终导致主机认为设备异常。

解决办法有两个方向：一是把Flash操作放到应用层任务里，用信号量告知USB回调层“数据已接收、马上写”，但这会改变TinyUSB的处理模型，复杂度高；二是优化Flash写入流程，把数据先在RAM里攒够一个4KB扇区再一次性擦写，期间短暂阻塞是可以接受的，只要阻塞时间在一个合理范围内。我个人的经验是先做容量适配和日志调试，确认SCSI命令流程没问题，再考虑并发优化。

还有一类问题是tud_msc_scsi_cb返回了错误状态，比如Windows在格式化时会发MODE SENSE(6)查询介质写保护状态，如果这个命令返回异常，Windows可能认为U盘只读或直接中止格式化。调试这类问题，最简单的方法是把CFG_TUSB_DEBUG调到2，TinyUSB会通过串口输出大量协议栈日志，配合一个USB转串口模块，很快就能定位到是哪条SCSI命令被拒绝。

6.4 常用工具清单与我的调试顺序

这里列一下我常用的工具，基本是免费的，遇到问题按这个顺序走，能省掉大量无效尝试。

最后分享一个我一直在用的调试顺序：代码能烧进去，先不急着插USB，用串口确认TinyUSB初始化成功；然后插USB，看设备管理器有没有“未知设备”，有就说明枚举失败，优先查描述符和硬件；没有未知设备但也没有U盘，查容量回调和磁盘管理；有U盘但读写失败，开TinyUSB日志逐条分析SCSI命令。按这个顺序走，绝大多数问题半小时内能定位。

我个人在实际操作中的体会是，TinyUSB做MSC设备最大的价值不是省下了写协议栈的时间，而是把“USB驱动开发”这个听起来很高的大门，变成了“填几个回调函数”这种很具体的小事。只要先把RAM Disk版跑通，再往Flash上迁移，整个过程的成功率会高很多。如果你准备拿这个方案做东西，建议从一开始就把Flash容量和文件系统规划好，哪怕第一版只跑RAM Disk，也要为后面的产品化留好接口。这个内容后续也可以进一步扩展：配合一个简单的Bootloader，把U盘当成固件升级入口，电脑端拷入bin文件就能完成OTA，整套方案会变得非常完整。