最近项目里要把 ESP32-S3 模拟成一个 USB MSC 设备，也就是让电脑把这块开发板当成一个 U 盘来访问。听起来不算复杂，TinyUSB 官方示例也现成，但真正调起来才发现，枚举失败、驱动安装报错、文件拷一半掉线、Windows 提示“需要修复”……每个坑都能让人折腾一整天。这篇就把整个调试过程从头到尾记录下来，包括硬件连接的几个隐藏陷阱、TinyUSB 代码骨架、完整排查链路，以及用 USB 抓包实锤定位问题的方法。
这篇内容适合正在用 ESP32-S3 / ESP32-S2 做 USB 设备开发的人，尤其是第一次碰 MSC（Mass Storage Class，大容量存储类）的朋友。文章不会只贴代码，更多是讲清楚每一步为什么要这样做，以及出问题时的排查思路。
1. ESP32-S3 的 USB 硬件底子：选型前先搞清楚能不能做 MSC
1.1 MSC 不是什么“高大上”的协议，但也不是随便一个 USB 口就能跑
MSC 是 USB 里的一个大容量存储类协议，核心思想就是主机端把设备当成一块硬盘或者 U 盘，通过读写扇区来存取数据。它的好处是主机不需要安装额外驱动——Windows、macOS、Linux 原生支持，插上就能识别。所以很多嵌入式设备需要导出数据、升级固件时会选择模拟成 U 盘，用户体验最好。
但这里有个容易被忽略的前提：要做 MSC 设备，芯片必须带USB Device（从机）控制器，而且这个控制器要支持至少一个 Bulk 端点对。普通串口转 USB 芯片、或者只带 USB-to-UART 桥接功能的芯片是做不了真正 MSC 的。有的 MCU 上面那个 USB 口只是给串口下载用的，它内部的 USB 外设只实现了 CDC（虚拟串口）功能，虽然也能枚举成设备，但不可能变成 U 盘。
ESP32-S3 的优势就在于，它内部有两套独立的 USB 硬件：一套是USB OTG（也常叫 USB-OTG-FS），一套是USB Serial/JTAG。前者可以自由配置成 MSC、CDC、HID 甚至是复合设备，后者只是固定用来做调试串口和 JTAG 的。所以做 MSC 时，必须把 USB OTG 这路引出来，不能用默认的 USB Serial/JTAG 引脚去接电脑——那是另一套外设，枚举出来的是串口，不是 U 盘。
1.2 S3 的 USB OTG 是 Full Speed，不是 High Speed，期望要摆正
很多第一次做 USB 的人会在心里默认“USB 嘛，至少也得几十 MB/s”，实际完全不是这么回事。ESP32-S3 的 USB OTG 只支持Full Speed（全速，12Mbps），不支持 High Speed（高速，480Mbps）。12Mbps 是理论链路速率，MSC 的 Bulk-Only 传输实际有效载荷还要打折扣，再加上协议开销和 SD 卡读取时间，实测稳定写速能到 1MB/s 左右就算不错了。
这里不是劝退，而是让大家提前把性能预期摆正。这个速度做配置文件导出、日志下载、几 MB 级别的固件拷贝完全够用，但想通过它做高速数据备份，趁早换方案。调试时如果发现读写速度上不去，先别怀疑代码，先确认链路本身就只有 12Mbps。
另外注意，S3 的 USB OTG 内部没有 PHY 的某些辅助电路，VBUS 检测和 ID 检测引脚需要外部处理。这也是很多新手第一个坑：硬件上只把 D+/D- 接上去，结果电脑毫无反应。
1.3 S2 / S3 / C3 的 USB 能力对比
| 芯片 | USB Serial/JTAG | USB OTG | 能否做 MSC | 备注 |
|---|---|---|---|---|
| ESP32-S3 | 有 | 有 | 可以 | 本文主角，两个 USB 外设可同时存在 |
| ESP32-S2 | 无 | 有 | 可以 | 同样能跑 TinyUSB MSC，但没有原生调试串口 |
| ESP32-C3 | 有 | 无 | 不可以做常规 MSC | 只有 Serial/JTAG，枚举为 CDC 类 |
这个表值得在选型时贴墙上。C3 虽然便宜，但它的 USB 口没法变成 U 盘。S2 能做 MSC，但板子上如果没有额外引出 UART，调试会麻烦不少，因为没有 USB Serial/JTAG 那套独立外设。S3 是两个都有，调试串口和 USB OTG 同时存在，是最省心的选择。
2. 硬件连接：DP/DM/ID/5.1k下拉这几个坑一次讲明白
2.1 DP/DM 引脚是固定的，不能随便映射
ESP32-S3 的 USB OTG 引脚固定为 GPIO20（D+）和 GPIO19（D-），不经过 GPIO 矩阵，不能像普通 GPIO 那样重新映射到别的引脚。这一点和 UART、SPI 完全不同，板子画错了就只能飞线。所以画 PCB 或者接线之前，第一件事就是确认这两个引脚没有被复用。
S3 的 USB OTG 还需要开启内部的 3.3V 稳压供电，这个在 IDF 菜单里有对应配置，后面会讲到。硬件上 D+/D- 对地各加一个 15kΩ 下拉电阻是参考设计里的做法，实际很多模块不焊也能用，但建议按官方参考设计来，稳定压倒一切。
调试初期建议直接在开发板上操作，因为很多 S3 开发板已经引出了 USB OTG 的 D+/D- 排针，避免自己飞线的时候把差分信号线拉太长。我当时犯过一个错：用杜邦线把 D+/D- 飞出去 20 厘米接到一个 USB 座子上，结果枚举时好时坏，换成短线和洞洞板直接焊之后才稳定。USB 全速虽然对信号完整性要求不如高速那么苛刻，但飞线超过 10cm 后尽量用双绞或者地线包裹。
2.2 5.1k 下拉电阻，到底什么时候才需要
网络热词里有一条“USB 的 CC 引脚有一个 5.1k 下拉，那怎么切换到主机模式”，这是典型的 USB-C 和 OTG 概念混淆。
先说结论：如果你用的是普通 USB-A 转 Micro-B 或 Type-C 线，把 S3 当设备（Device）插电脑，那么不需要 CC 下拉电阻，需要的是 D+/D- 上拉到 3.3V 吗？也不需要，那是 Apple 设备识别的做法，常规 PC 不管。需要关注 5.1k 下拉的场景是：你做了一个 USB-C 母座，想让 S3 作为 Device 插到电脑的 USB-C 口，这时母座这边的 CC1/CC2 各下拉 5.1kΩ 到 GND，让电脑识别到这是一个 UFP（Upstream Facing Port，也就是设备端）。
反之，如果你想用 S3 做主机（Host）去插 U 盘，USB-C 母座那边就要在 CC 上各上拉 5.1kΩ，同时把 ID 引脚拉低。热词里“怎么切换到主机模式”的答案就是：ID 引脚接地，而 CC 上拉不是“主机模式”的必要条件，只是 USB-C 接口的协商电阻。
ID 引脚在 S3 的 USB OTG 里也要留意。做纯 Device 时，ID 脚悬空或者接高都可以；做 OTG 主机时，ID 必须拉低。我见过有人把 ID 悬空就想去读 U 盘，结果是设备始终枚举成 Device 模式。S3 的 USB OTG 模式切换是可以靠软件配置的，但硬件上的 ID 状态会直接影响部分 SDK 的默认判断。
2.3 供电和信号质量：不要忽略 ESD 和 VBUS
USB 调试最容易忽视的是供电。S3 开发板一般有 5V 输入接口，但如果你用 USB 公头直接插电脑供电，要考虑板子整体电流能不能压住。MSC 场景下 SD 卡写入瞬间电流不小，如果 USB 供电走的是线性稳压，压降一大就会复位，表现就是设备枚举成功后一读写就断连。
另一个建议是 USB D+/D- 线上加 ESD 保护二极管。调试阶段可能觉得没必要，但如果是做产品或者长时间插拔测试，ESD 导致的枚举不稳定非常难排查，因为它不规律、复现难。哪怕用一个最便宜的 USBLC6-2，也能省掉很多莫名其妙的“接触不良”。
VBUS 检测方面，S3 的 USB OTG 模块有 VBUS 检测引脚，但很多开发板并没有连出来。IDF 的 TinyUSB 示例里，通常可以通过tinyusb_driver_install配置vbus_monitor_io为-1，表示不监测 VBUS。如果开发板确实引出了 VBUS 检测脚，建议接上，这样可以在代码里感知“USB 线拔了”，主动卸载文件系统，避免 SD 卡文件损坏。
2.4 SD 卡模块和接线参考
我做的是“SD 卡内容通过 USB 暴露成 U 盘”的方案，SD 卡用的 SPI 模式，接法如下：
| SD 卡模块引脚 | ESP32-S3 GPIO |
|---|---|
| CS | GPIO10 |
| SCK | GPIO12 |
| MOSI | GPIO11 |
| MISO | GPIO13 |
| VCC | 3.3V |
| GND | GND |
注意 SD 卡的 SPI 不能用硬件 SPI 的默认引脚就用，也要确认一下是不是被其他外设占用了。S3 的 GPIO 矩阵可以映射 SPI，比较灵活，但建议固定用一组，别换来换去。
SD 卡用 SPI 模式时，Class 10 的卡写入速度可能只有 1~2MB/s，搭配 USB FS 的 1MB/s 反而刚好不构成瓶颈。但如果你的卡特别旧或者扩容卡，写一半超时会导致主机报错，后面讲回调阻塞时会细说。
3. TinyUSB MSC 代码骨架：回调比描述符更关键
3.1 为什么直接上 TinyUSB，而不是自己写 USB 协议栈
ESP-IDF 自带的 USB 底层驱动比较偏硬件抽象，真要自己从零写 MSC 类，需要处理 CBW、CSW、SCSI 命令等一系列状态机，工作量很大而且容易藏 bug。TinyUSB 是开源社区用得最广的 USB 协议栈，ESP-IDF 已经把它作为组件内置，idf.py menuconfig里打开 TinyUSB 支持就能直接用。
TinyUSB 对 MSC 的封装比较友好，它把我们最头疼的 SCSI 命令解析、端点调度都做掉了，我们只需要提供 6 个回调函数，告诉它“我的磁盘容量多大、怎么读扇区、怎么写扇区”。这也是这篇强调“回调比描述符更关键”的原因——描述符只要照着填，枚举基本能过；但读写数据不稳、主机反复报错，问题基本都出在回调实现上。
3.2 描述符配置要点
TinyUSB 的 MSC 描述符本身不难，核心信息是接口描述符里的三个字节：bInterfaceClass = 0x08（Mass Storage），bInterfaceSubClass = 0x06（SCSI Transparent Command Set），bInterfaceProtocol = 0x50（Bulk-Only Transport）。这三个字节错了，Windows 会直接无法识别或安装驱动失败。
另外设备描述符里建议设置idVendor和idProduct。乐鑫的默认 VID/PID 可以用，但如果打算长期用，建议申请一个自己的 PID。字符串描述符也尽量写上厂商名、产品名和序列号，Windows 的设备管理器和驱动安装过程会读这些字符串，缺失时虽然能枚举，但排查问题时信息少一大截。
配置描述符里需要有一个 Bulk IN 端点和一个 Bulk OUT 端点，端点大小建议设置成 64 字节（全速 Bulk 端点最大就是 64）。这个值不要随意改小，否则主机会多很多事务，速度更慢。
3.3 六个回调怎么配合
TinyUSB MSC 核心回调如下，我用的是 IDF 5.x + TinyUSB 0.15 左右的接口：
// 0x12 INQUIRY：主机询问设备信息 bool tud_msc_inquiry_cb(uint8_t lun, uint8_t vendor_id[8], uint8_t product_id[16], uint8_t product_rev[4]) { const char vid[] = "ESP"; const char pid[] = "MassStorage"; const char rev[] = "1.0"; memcpy(vendor_id, vid, 8); memcpy(product_id, pid, 16); memcpy(product_rev, rev, 4); return true; } // 0x25 READ CAPACITY(10)：主机询问容量和扇区大小 bool tud_msc_read_capacity_cb(uint8_t lun, uint32_t* block_count, uint32_t* block_size) { *block_size = 512; *block_count = total_blocks; // 根据 SD 卡容量计算 return true; } // 0x23 READ FORMAT CAPACITIES：部分主机会先读这个 bool tud_msc_read10_cb(uint8_t lun, uint32_t lba, uint32_t offset, void* buffer, uint32_t bufsize) { // 从 SD 卡读取 lba 对应的块到 buffer，offset/bufsize 做对齐处理 return sd_read_blocks(lba, buffer, bufsize / 512); } // 0x2A WRITE(10)：主机写数据 bool tud_msc_write10_cb(uint8_t lun, uint32_t lba, uint32_t offset, uint8_t* buffer, uint32_t bufsize) { return sd_write_blocks(lba, buffer, bufsize / 512); } // 同步缓存（如果有写缓存可以在这里 flush） bool tud_msc_flush_cb(uint8_t lun) { return true; } // 检查设备是否 ready：SD 卡挂载成功后返回 true bool tud_msc_test_unit_ready_cb(uint8_t lun) { return sd_card_ready; }这段代码本身不复杂，真正的坑在别处：回调里的参数lba是按“扇区号”来的，而bufsize是字节数。我见过有人直接把bufsize当 LBA 用，往 SD 卡里写的位置完全错了，拷进去的文件能看见名字，一打开就是损坏。读取的时候一定要做一次bufsize / 512转换成扇区数。
3.4 磁盘缓冲：对齐、回调不能阻塞、小心栈空间
MSC 回调是在 TinyUSB 任务上下文里执行的，Windows 对枚举和读写有严格超时要求。全速设备单块 512 字节的读写，如果回调里同步去读 SD 卡，偶尔慢一次可能问题不大，但如果连续读写大文件，SD 卡 SPI 模式一个块读 2ms，累计起来很容易超过主机的超时阈值。
这里有两层优化思路：
第一，缓冲区对齐。TinyUSB 传入的buffer需要对齐到 4 字节以上，SD 卡 SPI 驱动要求缓冲区 4 字节对齐。用heap_caps_malloc(4096, MALLOC_CAP_DMA)申请 DMA 安全的缓冲区能避免很多缓存一致性问题。
第二，不要在回调里做耗时操作。更稳妥的做法是回调里只把请求丢给一个待处理队列，由专门的读取任务操作 SD 卡，再通过信号量通知完成。但这个方案要做传输完成通知，TinyUSB 有tud_msc_xfer_cb之类的接口，比较复杂。我实测下来，只要 SD 卡质量正常、读取函数不反复初始化 SPI，直接在回调里同步读写 512 字节基本可行，但如果遇到写大文件掉线，优先改成队列异步处理。
另外千万别在回调里调用printf变长日志。USB MSC 回调里做耗时的串口输出，会把整个 USB 调度卡死，现象就是设备掉线。调试时可以加日志，但正式跑之前必须去掉。
4. 枚举失败到驱动安装报错：一条完整的排查链路
4.1 现象一：插上电脑毫无反应，设备管理器里什么都没有
遇到这种问题，不要急着看代码，先看硬件链路。USB 枚举的第一步是主机往设备发复位信号，然后设备要在 D+ 上拉一个 1.5kΩ 电阻（通常由 USB 控制器内部完成），让主机识别到全速设备。如果插上去完全没反应，八成是设备端根本没“活”过来。
排查顺序：
- 用万用表量 VBUS（5V）有没有到板子。
- 量 GPIO20（D+）和 GPIO19（D-）对地电压。全速设备空闲时，D+ 应该被拉高到 3.3V 附近。如果 D+ 是 0V，说明 USB 控制器没启动，或者固件没有调用
tinyusb_driver_install。 - 确认固件里启用了 TinyUSB 组件，且配置的 USB 模式是 Device/OTG Device 模式。
- 确认使用的是 USB OTG 引脚，不是 USB Serial/JTAG 引脚。
我犯过的低级错误是：板子上的 USB 口走的是 USB Serial/JTAG 引脚，固件里配置的却是 USB OTG，结果插上后设备管理器里只出现一个“USB 串行设备”，根本不是 U 盘。接线和配置必须两边对齐。
4.2 现象二：设备管理器出现黄色感叹号，错误码 43 或“无法识别的 USB 设备”
这个阶段说明 USB 枚举已经开始了，设备地址也拿到了，但在获取配置描述符或者设置配置阶段失败。最常见的原因是描述符里的类信息不对，或者字符串描述符索引越界。
打开 Wireshark 抓包能看到主机反复发GET_DESCRIPTOR，设备要么不回包，要么回的长度不对。经验是先用电脑端USBDeview或UsbTreeView这类工具看设备枚举到了哪一步，能读到设备描述符说明底层没问题，之后报错多半在配置描述符。
一个非常隐蔽的问题：tud_msc_inquiry_cb返回的 VID 字符串必须是 8 字节，不足的部分要补空格，不能直接memcpy一个短字符串。Windows 对 INQUIRY 数据长度要求严格，短一字节就可能导致枚举到一半设备被判定为无效，表现为“无法识别的 USB 设备”。
4.3 现象三：驱动安装失败，“Windows 无法加载这个硬件的设备驱动”
这个报错我一开始也遇到过，查了很多资料才发现是描述符里bcdUSB版本写太高。Windows 对 USB 版本有兼容性判断，版本号高于控制器支持等级时，部分机器会拒绝加载驱动，或者加载 USB 大容量存储设备驱动失败。
把bcdUSB设置成0x0200（USB 2.0）是最稳妥的做法，不要写成 0x0300，哪怕硬件其实是 USB 2.0 全速，也不要标 USB 3.0。另外配置描述符里bMaxPower不要写 0，Windows 通常能容忍 0，但有些 USB 集线器芯片会因此拒绝供电。
另外注意，Windows 对第一个配置描述符的wTotalLength很敏感。如果长度和实际返回的数据不一致，要么识别不了，要么出现“设备描述符请求失败”。建议代码里用sizeof(config_desc)自动填充，不要手写死长度。
4.4 排查顺序速查表
| 现象 | 优先排查 | 手段 |
|---|---|---|
| 毫无反应 | VBUS/D+电压 | 万用表 |
| 枚举到一半掉线 | 供电不足、DP/DM信号质量 | 短接线、示波器 |
| 设备管理器感叹号 | 配置描述符、类代码 | USBDeview、抓包 |
| 驱动安装失败 | bcdUSB、字符串描述符 | 修改描述符重刷 |
| 能枚举不能读写 | SCSI 回调、SD 卡就绪状态 | 抓包、串口日志 |
这张表也是我的排查“肌肉记忆”：从最底层往上层一层层看，不要一上来就怀疑 TinyUSB 库本身，绝大多数问题都出在自己写的回调、描述符或者硬件接线上。
5. USB 抓包复盘：把枚举过程拉出来实锤
5.1 抓包环境配置，Windows 一条龙
USB 抓包是定位这类问题最直观的手段。Windows 下推荐 Wireshark 加 USBPcap，安装时勾选 USBPcap，打开 Wireshark 后选择 USBPcap 接口，插拔一次 USB 设备就能看到枚举流量。
Linux 下更省事，主线和usbmon模块一加载，Wireshark 直接选usbmon0接口。嵌入式开发如果常用 Linux，建议抓包在 Linux 上做，过滤起来比 Windows 方便。
抓枚举的时候，把之前插过的设备拔掉，先开抓包再插 USB，这样能看到从GET_DESCRIPTOR Device到SET_CONFIGURATION的完整过程。过滤条件用usb.idVendor == 0x303a（乐鑫的 VID）配合usb.urb_type == URB_SUBMIT，能只看主机发出来的请求。
5.2 正常枚举应该看到哪些包
我先说正常流程，大家对照抓包：
- 主机发送
GET_DESCRIPTOR Device，设备返回 18 字节设备描述符。 - 主机发送
SET_ADDRESS，设备地址从 0 变成新地址。 - 主机重新
GET_DESCRIPTOR Device，确认新地址工作正常。 - 主机发送
GET_DESCRIPTOR Config，设备返回配置描述符全文。 - 主机可能发送
GET_DESCRIPTOR String，获取厂商、产品、序列号。 - 主机发送
SET_CONFIGURATION，设备开始工作。
对 MSC 设备，SET_CONFIGURATION之后，Windows 会立刻发INQUIRY、READ CAPACITY、TEST UNIT READY等一系列 SCSI 命令。抓包里如果只看到枚举到SET_CONFIGURATION就没了，说明设备没在 SCSI 层回应，问题在回调。
5.3 一次失败枚举的实测分析
我调试过程中遇到过一次很典型的失败：抓包里主机反复发送GET_DESCRIPTOR Config，设备回了 9 字节就停了。这明显是配置描述符里bNumInterfaces和实际接口数量对不上，主机以为后面还有接口描述符，设备却已经回完了。
另一个案例是GET_DESCRIPTOR String索引越界。我把字符串描述符数组定义成了 3 个，但配置描述符里iInterface写成 3，结果主机一请求索引 3 的字符串，设备直接不响应，USB 总线就挂了。用iInterface = 0可以彻底避开这个问题，代价是部分调试工具看不到接口名称，但功能不会受影响。
所以抓包的重点不是看所有细节，而是看“主机发了什么请求，设备有没有回应、回应了什么”。一旦发现某个请求石沉大海或者回复长度不对，问题基本就锁定在对应描述符索引或回调上了。
5.4 从抓包看 USB-C CC 下拉误区
热词里那句“usb 的 cc 引脚有一个 5.1k 下拉，那怎么切换到主机模式”，抓包完全能解释：
如果你用 Type-C 转 Type-C 线连接 S3 的 Type-C 母座和电脑，设备端 CC 必须有 5.1k 下拉到 GND，电脑才能识别到这是一台设备，并且通过 CC 协商供电。抓包里体现为 VBUS 先上电，然后才出现枚举请求。如果 CC 没有下拉，或者做成了上拉，电脑那边根本不会给 VBUS 供电，USB 枚举包一包都看不到。
所以“怎么切换到主机模式”的答案在硬件上就是：ID 拉低 + CC 上拉 5.1k（Type-C 口场景）。如果是传统 Micro-B 口，没有 CC，切主机模式只要 ID 拉低就行。抓包时如果 VBUS 都没起来，先检查 CC 电阻，而不是抓包软件。
6. 读写掉线、文件损坏、蓝屏：MSC 真正难啃的收尾
6.1 枚举全过了，但 Windows 提示“需要修复”或者拷文件掉线
能枚举不代表 MSC 做好了。枚举成功只是 USB 层通了，真正影响体验的是 SCSI 层的读写实现。
最容易遇到的现象是：插上 U 盘后 Windows 弹窗“此驱动器有问题，需要扫描并修复”，或者打开盘符能看到文件，但一复制大文件就报错。前者通常是文件系统元数据读取有问题，后者多数是读写缓存或块重试逻辑有问题。
先排除一个最基础的问题：分区和文件系统。MSC 设备暴露的是一整块磁盘，Windows 会读取 0 号扇区的 MBR/分区表。如果 SD 卡是裸的、没有分区表和 FAT32 文件系统，Windows 会提示“需要格式化”。这不是代码 bug，而是 SD 卡还没准备好。在电脑上用工具格式化成 FAT32，再插到 S3 上做 MSC 测试，能避免把文件系统问题混进 USB 问题里。
6.2 扇区对齐与回调阻塞：Windows 对超时零容忍
Windows 的 USB 大容量存储驱动对命令超时非常敏感，单条 SCSI 命令超时后它会重试，连续重试失败就会把设备判为故障，直接掉线。SD 卡 SPI 读取如果遇到坏块，或者回调里做了一个耗时的fflush，都可能触发超时。
解决思路第一层是：确保tud_msc_read10_cb和tud_msc_write10_cb返回之前，数据真正落盘或确凿读出来了，不要返回成功但没做完。第二层是：如果 SD 卡驱动支持，开启 4 位 SDIO 模式能明显减少单块读写时间。第三层是：写回调里如果做日志输出，务必去掉。
这里有个实测结论：SPI 模式 SD 卡读取单块 512 字节大约 0.3~2ms，全速 USB 单块传输本身约 0.5ms，组合起来基本能跑，但连续写大文件时写缓存必须处理好。我一开始用的是 FatFs 的f_mount然后直接disk_write，回调里每次写都调disk_write返回后才回 TinyUSB，大文件写到一半就掉线。改成回调里只做sd_write_blocks，不涉及文件系统层之后，问题就消失了。
关键原则：MSC 回调工作在块设备层，不要碰文件系统层。文件系统是主机那边的事，设备只负责“给我 LBA 我就读/写这块”。
6.3 SCSI 状态与 SenseKey：为什么主机反复重试
另一个排查了很久的问题：主机发READ(10)，设备返回失败后，Windows 并不会马上放弃，而是会发REQUEST SENSE查询具体错误原因。如果你的回调返回 false，但没有设置 SenseKey，部分主机会一直重试，表现就是设备管理器里反复“正在安装设备驱动”、盘符一闪一闪。
TinyUSB 对回调返回 false 的处理会比较简单，默认可能返回CHECK_CONDITION但没有具体 Sense 数据。调试期为了简单，建议tud_msc_test_unit_ready_cb只有在 SD 卡真正就绪时才返回 true，否则返回 false。这样主机在 SD 卡初始化完成前会一直等，而不是读到一半失败。
如果想让错误处理更规范，可以在返回 false 的同时设置scsi.sense.key等字段，但 TUD 的默认实现不一定暴露这些接口，需要自己去扩展。对于大多数应用，保证“就绪前不回调读写”就够了。
6.4 掉电安全：拔线时文件损坏几乎必现
MSC 设备天然有这个弱点：主机认为数据写完了，但 SD 卡可能还在 flush 缓存。如果用户随时拔线，文件损坏几乎无法完全避免。硬件上能做的最有效一件事就是 VBUS 检测，检测到掉电立刻进入“卸载文件系统”流程。
S3 的tinyusb_driver_install支持vbus_monitor_io参数，把 VBUS 检测脚连到 GPIO 上，配合事件回调，能在拔线的瞬间感知。实测加上这个之后，异常拔线导致的 SD 卡文件损坏概率明显下降，但还不是零。想更保险只能引导用户“安全弹出”，这是协议和系统层面的限制，不是代码能完全解决的。
另外，TinyUSB 的tud_msc_flush_cb要正确返回。Windows 在弹出设备时会下发SYNCHRONIZE_CACHE或START_STOP_UNIT，如果flush和stop回调没有把缓存真正落盘，弹出后数据一样会丢。我建议在tud_msc_flush_cb里做一次 SD 卡缓存同步，把 FatFs 的f_sync逻辑放到这个回调里执行（如果有文件系统层的话），保证“安全弹出”时数据完整。
写在最后的调试小抄
USB MSC 调试最怕的不是难，而是信息不透明。设备管理器只给你一个黄色感叹号，Wireshark 抓包能让你看到主机到底在等什么。我个人的习惯是：硬件上用最短的线、独立供电；固件上先跑通 TinyUSB 官方 MSC 示例，再用自己的 SD 卡读写函数替换；抓包只要看到SET_CONFIGURATION之后的 SCSI 命令流，就说明 USB 层已经通了；后面所有读写问题，都回到回调函数的时序和数据内容上去查。
如果非要再说一条最容易被忽略的经验：SD 卡先格式化好 FAT32、插到电脑上验证过能读写，再接到 S3 上做调试。这一步能帮你把“SD 卡自身问题”和“USB MSC 实现问题”彻底分开，省下大量无意义的排查时间。MSC 调试本质上就是一层一层剥开协议栈，只要每一层都有明确的现象和验证方法，再奇怪的 bug 也能被一步步逼出来。
