usbtree是什么:终端USB设备树查看器完全指南(1.5MB单文件、免root、跨三大平台)
usbtree是什么:终端USB设备树查看器完全指南(1.5MB单文件、免root、跨三大平台)
usbtree 是一款运行在终端里的 USB 设备树查看器(Terminal UI 工具):输入一个命令,即可在 Linux、macOS、Windows 三大平台实时查看电脑里插着哪些 USB 设备、它们挂在哪个集线器(Hub)下、速度是多少,还能看到每个设备的实时流量曲线。它由 Rust 编写,依赖纯 Rust 的 nusb 库枚举设备,不需要 root 权限、不需要安装 libusb,下载仅约 1.5 MB,是一个零运行依赖的静态二进制文件。
为什么需要 usbtree?
排查 USB 问题(U 盘识别慢、鼠标卡顿、设备掉速)时,普通用户面对的往往是枯燥的命令行输出或图形化设置界面:
- 不知道某个设备挂在哪个 Hub 端口下;
- 设备标称 USB 3.0 却只跑出 USB 2.0 速度;
- 插拔设备后想知道系统看到了什么。
usbtree 把这些信息以彩色树状图实时呈现在终端中:每秒自动重扫一次,按设备类(Hub / HID / Audio / Storage / Video)着色分类,用 ▂、▄、█ 等速度徽标直观区分全速、高速(480M)和 SuperSpeed+(5G/10G)。
三大卖点:1.5MB 单文件、免 root、跨平台
| 特点 | 说明 |
|---|---|
| 📦 1.5 MB 单文件 | 下载约 1.5 MB,落盘 5–7 MB,无运行时依赖,拷贝即用 |
| 🔓 免 root | 基于纯 Rust 的 nusb 库枚举设备,无需 libusb、无需管理员权限(Linux 上查真实字节/秒才需 root,见下文) |
| 🖥️ 三大平台 | Linux(amd64/arm64)、macOS(arm64)、Windows(amd64)均提供预编译二进制 |
| ⚡ 实时刷新 | 每秒重扫一次,热插拔即时显示,拔下的设备以红色"幽灵"形式保留 30 秒并记入事件日志 |
技术实现上,主循环与界面绘制在 src/main.rs,设备扫描与 sysfs 风格路径(如 1-1.4 = 总线1-端口1-端口4)构建在 src/usb.rs,活动指标采集在 src/metrics.rs。
快速安装:四种方式任选其一
Homebrew(Linux / macOS Apple Silicon)
brew install usbtree
Linux / macOS(脚本安装)
curl -fsSL https://raw.githubusercontent.com/gnomeria/usbtree/main/scripts/install.sh | sh
Windows(PowerShell)
irm https://raw.githubusercontent.com/gnomeria/usbtree/main/scripts/install.ps1 | iex
从源码安装
cargo install --git https://github.com/gnomeria/usbtree
安装脚本位于 scripts/install.sh 与 scripts/install.ps1,会自动校验 sha256 并安装到用户目录,全程无需 sudo。安装完成后直接运行 usbtree 即可进入 TUI;若没有真实 USB 硬件,可先运行 usbtree --demo 体验一棵带脚本化热插拔和流量演示的虚拟设备树。
⚠️ macOS / Windows 二进制未做代码签名:macOS 首次运行需解除隔离属性(安装脚本会自动处理),Windows SmartScreen 警告时选"仍要运行"即可。
界面全解:设备树 + 详情面板 + 事件日志
界面分为四个区域:
- tree(设备树):所有 USB 设备按端口层级展示,左侧色条标识设备类,每行显示设备名、速度徽标、
bMaxPower与实时流量迷你图(sparkline); - details(详情面板):选中设备后显示 sysfs 路径、vid:pid、厂商、类、速度、序列号、已连接子设备,以及带宽走势图;
- events(事件日志):热插拔事件按时间戳记录,插入为绿色、拔出的"幽灵"为红色;
- 底部快捷键栏:常驻提示所有可用按键。
支持鼠标点击选中、滚轮滚动,也可纯键盘操作。常用快捷键:
| 按键 | 作用 |
|---|---|
j/k、方向键 |
上下移动选择 |
Enter/Space |
折叠/展开 Hub |
h/l |
收起 / 展开分支 |
g/G |
跳到顶 / 底 |
/ |
实时过滤设备(折叠的 Hub 内也能搜到) |
y / Y |
复制 vid:pid / 完整详情 |
e |
安全弹出存储设备(Linux) |
p |
USB / PCI 视图切换 |
t |
切换主题(--light 可用浅色主题) |
q / Esc |
退出 |
Linux 专属:实时活动指标怎么看?
顶栏会显示当前数据源,这是 Linux 用户最关心的部分:
◌ urb activity(默认,免特权):读取 sysfs 的urbnum计数差值,显示每秒 URB 请求数——无需 root 即可看到"哪个设备在忙";◉ usbmon bytes/s(需 root):通过 usbmon 内核模块读取真实字节吞吐。
注意:只有 sudo 是不够的,还需加载 usbmon 模块,否则会静默回退到 URB 模式:
sudo modprobe usbmon
sudo "$(command -v usbtree)"
若想开机自动加载 usbmon,把 usbmon 写入 /etc/modules-load.d/usbmon.conf。macOS / Windows 没有免特权的逐设备流量计数器,顶栏会显示 ◌ activity n/a on this platform,但设备树、详情面板、热插拔事件日志均正常可用。
跨平台功能支持矩阵
| 功能 | Linux | macOS | Windows |
|---|---|---|---|
| 设备树(Hub、类、速度、树轨) | ✅ | ✅ | ✅ |
| 友好名称(overrides.ids + usb.ids) | ✅ | ✅ | ✅ |
| 热插拔监听 + 时间戳事件日志 | ✅ | ✅ | ✅ |
| 详情面板(sysfs 路径、vid:pid、序列号) | ✅ | ✅ | ✅ |
设备标称功耗 bMaxPower |
✅ | ✅ | — |
| 实时活动 sparkline(免特权 URBs/s) | ✅ | — | — |
| 真实带宽 bytes/s(usbmon,需 root) | ✅ | — | — |
PCI 视图(p 切换) |
✅ | — | — |
常用参数一览
| 命令 | 作用 |
|---|---|
usbtree |
进入 TUI |
usbtree --dump |
只打印一次设备树并退出(适合写进脚本) |
usbtree --updatelist |
下载最新 usb.ids 到配置目录,补全新设备名称 |
usbtree --demo |
虚拟演示树(脚本化热插拔 + 流量),无需硬件 |
usbtree --upgrade |
通过官方安装器原地升级到最新版 |
usbtree --light |
浅色主题(适配浅色背景终端) |
参数解析与帮助文案定义在 src/cli.rs,完整行为可查 usbtree --help。
个性化配置位于 ~/.config/usbtree/(Windows 为 %APPDATA%\usbtree\):
overrides.ids:自定义设备名,每行vvvv:pppp 友好名称,优先级最高;usb.ids:由--updatelist写入的设备 ID 数据库,优先于二进制内置快照。
从源码学习它的实现
项目结构非常清晰,适合想学 Rust TUI 的读者:
- src/main.rs — 事件循环、全部绘制逻辑与主题(Tokyo Night 为默认主题);
- src/usb.rs — 扫描、树构建/折叠、usb.ids 解析、demo 数据源;
- src/metrics.rs — URB 速率、usbmon 字节吞吐、演示流量合成;
- src/pci.rs — PCI 详情(prog-if、NUMA、IOMMU 组、链路速度/宽度);
- docs/screenshots/demo.png 与 docs/screenshots/demo.gif — 由 tapes/demo.tape 驱动的 VHS 无头渲染,脚本在 scripts/shots.sh。
常见问题 FAQ
Q1:为什么提示需要 root? 只有 Linux 上想看"真实字节/秒"(usbmon)才需要 root;日常查看设备树、URB 活动指标完全免特权。
Q2:设备名称显示为编号(如 0781:558c)?
运行 usbtree --updatelist 更新设备 ID 数据库,或在 overrides.ids 中手动添加友好名称。
Q3:Windows 下看不到流量曲线? 这是平台限制(无免特权的逐设备流量接口),但设备树、详情、热插拔日志在 Windows 上功能完整。
Q4:如何脚本化采集设备树?
usbtree --dump 打印一次即退出,可直接 | jq 或重定向到文件,方便纳入巡检脚本。
小结
usbtree 把"我的电脑上到底插了什么 USB 设备"这件事,变成了终端里一个每秒刷新、彩色分层的实时树:1.5 MB 单文件、免 root、三大平台通吃,Linux 用户还能免费获得实时活动指标,想要精确带宽再叠加 usbmon。对于排查 USB 故障、确认设备链路速度、监控外设活动的普通用户来说,它几乎是零成本的一站式方案。

