usbtree是什么:终端USB设备树查看器完全指南(1.5MB单文件、免root、跨三大平台)

原创2026-10-31 10:40:041,878 阅读

usbtree是什么:终端USB设备树查看器完全指南(1.5MB单文件、免root、跨三大平台)

usbtree 是一款运行在终端里的 USB 设备树查看器(Terminal UI 工具):输入一个命令,即可在 Linux、macOS、Windows 三大平台实时查看电脑里插着哪些 USB 设备、它们挂在哪个集线器(Hub)下、速度是多少,还能看到每个设备的实时流量曲线。它由 Rust 编写,依赖纯 Rust 的 nusb 库枚举设备,不需要 root 权限、不需要安装 libusb,下载仅约 1.5 MB,是一个零运行依赖的静态二进制文件。

usbtree 终端USB设备树查看器界面:左侧为带类图标和速度徽标的设备树,右侧为设备详情面板与实时带宽图

为什么需要 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 的读者:

usbtree 演示动图:实时设备树扫描与热插拔事件日志

常见问题 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 故障、确认设备链路速度、监控外设活动的普通用户来说,它几乎是零成本的一站式方案。

登录后查看全文
usbtree