1. 为什么 realsense-viewer 在 Ubuntu 20.04 上总装不上如果你手头有一台 D435i、D455 或者 T265插上 Ubuntu 20.04 的机器第一反应肯定是装个realsense-viewer看看深度图和 IMU 数据。但真正动手之后你会发现这件事远没有想象中那么顺——apt install找不到包源码编译到一半报内核头文件缺失好不容易编译完了运行起来又提示No device connected插拔几次 USB 之后设备干脆从lsusb里消失了。这些问题的根源其实不复杂但分散在好几个环节librealsense 的版本和内核 uvcvideo 模块的兼容性、USB 权限规则、内核头文件、以及 Ubuntu 20.04 默认的 udev 规则版本。任何一个环节没对上realsense-viewer 就跑不起来。而且这几个环节的报错信息往往互相掩盖你解决了 A 问题B 问题才暴露出来很容易让人以为是装不上。这篇内容面向的是在 Ubuntu 20.04Focal Fossa上第一次接触 RealSense 的开发者不管你是做 ROS 机器人、做三维重建还是单纯想验证一下手头相机的好坏这套流程都能直接复用。我会把整个安装过程拆成依赖准备 → 源码编译 → udev 规则 → 验证运行四个阶段每个阶段讲清楚为什么这么做以及实测中会踩到什么坑。全程基于 librealsense 官方源码编译路线不依赖任何第三方预编译包这样版本可控出问题也好排查。先给一个整体判断Ubuntu 20.04 上装 realsense-viewer推荐走源码编译而不是 apt。原因后面会详细说但简单讲就是 apt 源里的版本往往落后而且和你的内核版本不一定匹配源码编译虽然多花十几分钟但可控性高得多。2. 装之前必须搞清楚的三个前置条件2.1 内核版本决定了你能用哪个 librealsense 版本这是最容易被忽略的一点。librealsense 依赖内核的uvcvideo模块来访问 USB 摄像头而不同内核版本对 UVC 元数据的支持程度不一样。Ubuntu 20.04 默认内核是 5.4这个版本对 RealSense 的支持是基本可用但需要打补丁的状态。具体来说librealsense 从 2.34 版本开始引入了对内核 UVC 补丁的依赖如果你用的是 5.4 内核需要确认uvcvideo模块是否支持UVC_QUIRK_METADATA。检查方法很简单uname -r modinfo uvcvideo | grep -i version如果内核版本低于 4.16那基本不用折腾了深度流和 IMU 都会有问题建议先升级内核。5.4 到 5.15 之间是相对安全的区间5.15 以上对 RealSense 的支持更完善但 Ubuntu 20.04 默认不带这么新的内核需要自己装 HWE 内核sudo apt install linux-generic-hwe-20.04装完重启uname -r应该能看到 5.15 或更高。这一步不是必须的但如果你后面遇到深度流打不开、帧率不稳的问题回头升级内核往往能解决。2.2 USB 控制器带宽不是插上就能跑满帧率RealSense 相机对 USB 带宽很敏感。D435i 同时开深度 848x48090fps 加 RGB 1920x108030fps再加上 IMU总带宽需求接近 USB 3.0 的上限。如果你的机器上同时插了其他 USB 3.0 设备比如外接硬盘、采集卡带宽会被瓜分表现就是帧率掉、丢帧、甚至设备直接掉线。实测下来把 RealSense 单独插在一个 USB 3.0 控制器上是最稳的做法。用lsusb -t可以看到设备挂在哪个控制器下lsusb -t输出里ClassVideo那一行就是相机看它上面的5000M还是480M前者是 USB 3.0后者是 USB 2.0。如果显示 480M说明你插错口了或者线材不支持 USB 3.0。RealSense 原装线是 USB 3.0 的但很多人随手拿一根手机充电线就插上了那种线往往只有 USB 2.0 的线芯带宽根本不够。提示如果lsusb -t里相机挂在 USB 2.0 下先换线、换口别急着怀疑软件问题。这是最常见的设备能识别但跑不起来的原因。2.3 磁盘空间和编译依赖的提前准备源码编译 librealsense 需要下载大约 1GB 的源码和依赖编译过程还会产生几个 GB 的中间文件。建议预留至少 10GB 空闲空间。依赖包方面Ubuntu 20.04 上需要提前装好这些sudo apt update sudo apt install -y git cmake build-essential libssl-dev libusb-1.0-0-dev \ libudev-dev pkg-config libgtk-3-dev libglfw3-dev libgl1-mesa-dev \ libglu1-mesa-dev at libavcodec-dev libavformat-dev libswscale-dev \ python3-dev python3-numpy这里有几个包值得单独说libssl-devlibrealsense 的网络设备功能比如以太网连接的 D455需要它不装的话 cmake 阶段会直接报错。libgtk-3-dev和libglfw3-devrealsense-viewer 的 GUI 依赖不装的话编译出来的 viewer 是空的或者干脆编译不过。libusb-1.0-0-devUSB 通信的核心依赖版本不能太低Ubuntu 20.04 自带的 1.0.22 是够用的。python3-dev如果你后面要用 pyrealsense2这个必须有。这些依赖里libssl-dev和libgtk-3-dev是最容易漏的因为很多教程只列了前几个。漏了libgtk-3-dev的典型症状是 cmake 配置阶段提示Could NOT find GTK3然后 viewer 被跳过编译最后你装完发现根本没有realsense-viewer这个可执行文件。3. 源码编译 librealsense 的完整链路3.1 选对分支别直接 clone masterlibrealsense 的 master 分支是开发分支稳定性不如 release tag。实测下来用最新的 release tag 比 master 稳得多。截至我写这篇内容时比较稳的版本是 v2.54.2 和 v2.55.1前者兼容性更好后者对新固件支持更全。git clone https://github.com/IntelRealSense/librealsense.git cd librealsense git tag | tail -20 git checkout v2.54.2选 v2.54.2 的理由这个版本对 Ubuntu 20.04 5.4 内核的组合验证得最充分社区里踩坑记录也最多遇到问题好搜。v2.55 之后对内核版本要求提高了一些5.4 内核下偶尔会有 UVC 相关的警告。clone 完之后先别急着编译检查一下当前目录下有没有build文件夹有的话删掉避免旧缓存干扰rm -rf build3.2 内核补丁什么时候需要打什么时候不用librealsense 源码里带了一个scripts/patch-realsense-ubuntu-lts.sh脚本用来给内核的 uvcvideo 模块打补丁主要是为了支持硬件时间戳和元数据。这个脚本不是必须跑的取决于你的内核版本和使用场景。判断标准内核版本是否需要打补丁说明 4.16必须否则深度流无法工作4.16 - 5.4建议硬件时间戳需要普通使用可跳过5.4 - 5.15可选大部分场景不需要 5.15不需要内核已原生支持如果你只是跑 realsense-viewer 看图像5.4 内核下可以跳过打补丁直接编译。打补丁的风险是可能和当前内核的其他模块冲突导致编译内核模块失败反而更麻烦。我个人的做法是先不打补丁编译一次如果深度流正常、时间戳没问题就不折腾了。如果确实需要打补丁脚本执行前要确保装了当前内核的头文件sudo apt install linux-headers-$(uname -r)然后./scripts/patch-realsense-ubuntu-lts.sh这个过程会重新编译 uvcvideo 模块耗时大概 5-10 分钟。执行完需要重启或者手动modprobe -r uvcvideo modprobe uvcvideo重新加载模块。3.3 cmake 配置阶段的关键参数进入 build 目录开始配置mkdir build cd build cmake .. -DCMAKE_BUILD_TYPERelease \ -DBUILD_EXAMPLEStrue \ -DBUILD_GRAPHICAL_EXAMPLEStrue \ -DBUILD_PYTHON_BINDINGStrue \ -DPYTHON_EXECUTABLE$(which python3) \ -DFORCE_RSUSB_BACKENDfalse逐个解释这些参数CMAKE_BUILD_TYPEReleaseRelease 模式编译优化级别高viewer 跑起来流畅。Debug 模式编译慢且运行卡除非你要调试源码否则别用。BUILD_EXAMPLEStrue编译示例程序包括rs-depth、rs-color这些命令行工具排查问题时很有用。BUILD_GRAPHICAL_EXAMPLEStrue这个必须开realsense-viewer 就属于 graphical examples不开的话编译完没有 viewer。BUILD_PYTHON_BINDINGStrue编译 pyrealsense2后面用 Python 做开发的话需要。PYTHON_EXECUTABLE指定 Python 路径Ubuntu 20.04 默认是 python3不指定的话 cmake 可能找到 python2导致绑定编译失败。FORCE_RSUSB_BACKENDfalse这个参数很关键。设为 true 会强制使用 libusb 后端绕过内核 uvcvideo好处是不依赖内核补丁坏处是性能略低、部分功能受限。默认用 false走内核后端除非你内核版本太老或者打补丁失败才考虑设 true。cmake 配置完成后输出里会有一行Configuring done然后列出哪些组件会被编译。重点看这几行-- Building graphical examples: yes -- Building python bindings: yes -- Building with CUDA support: no如果 graphical examples 显示 no说明 GTK 或 GLFW 没找到回去检查依赖。CUDA 支持一般不需要除非你要做 GPU 加速的点云处理。3.4 编译和安装make -j 的坑配置没问题就可以编译了make -j$(nproc)-j$(nproc)是用满所有 CPU 核心并行编译能快不少。但这里有个坑内存不足的机器上并行编译会 OOM。librealsense 的某些源文件尤其是rs.cpp和device.cpp编译时内存占用很高4GB 内存的机器用-j4可能会被系统 kill 掉。判断方法如果 make 过程中突然报c: fatal error: Killed signal terminated program cc1plus那就是内存不够。解决办法是减少并行数make -j2或者干脆单线程make慢是慢点但稳。编译时间参考8 核 16GB 的机器-j8大概 8-12 分钟4 核 8GB 的机器-j4大概 15-20 分钟。编译完成后安装sudo make install sudo ldconfigldconfig是刷新动态链接库缓存不执行的话运行时会提示找不到librealsense2.so。3.5 验证安装是否成功装完之后先别急着插相机用命令行工具确认库本身没问题rs-enumerate-devices如果这个命令能跑起来哪怕提示没找到设备说明库装好了。如果提示command not found检查/usr/local/bin是否在 PATH 里或者make install是否真的成功了。再看一下库的版本rs-enumerate-devices --version输出的版本号应该和你 checkout 的 tag 一致。4. udev 规则设备识别不了的头号元凶4.1 为什么插上相机 lsusb 能看到但程序读不到这是最经典的问题lsusb里能看到Intel Corp.的设备但rs-enumerate-devices提示No device connected。原因几乎可以肯定是udev 规则没装或者没生效。Linux 下普通用户默认没有权限直接访问 USB 设备节点RealSense 需要 udev 规则来给设备节点设置正确的权限和用户组。librealsense 源码里带了规则文件config/99-realsense-libusb.rules需要手动拷贝到系统目录sudo cp config/99-realsense-libusb.rules /etc/udev/rules.d/ sudo udevadm control --reload-rules sudo udevadm trigger注意路径如果你已经 cd 到 build 目录了规则文件在上一级的config目录里路径是../config/99-realsense-libusb.rules。4.2 规则文件里的关键字段解读打开这个规则文件看一眼核心内容大概是这样SUBSYSTEMusb, ATTRS{idVendor}8086, ATTRS{idProduct}0b07, MODE0666, GROUPplugdevidVendor8086Intel 的 USB 厂商 IDRealSense 全系都是这个。idProduct不同型号不同0b07 是 D435i0b3a 是 D4550b3d 是 T265规则文件里列了一长串。MODE0666给设备节点设置读写权限所有用户可读写。GROUPplugdev把设备归到 plugdev 组。这里有个细节你的用户必须属于 plugdev 组否则即使规则生效权限也不一定对。检查groups $USER如果没有 plugdev加进去sudo usermod -aG plugdev $USER加完组需要重新登录才生效或者用newgrp plugdev临时切换。很多人改完规则发现还是不行就是因为没重新登录。4.3 规则生效的验证方法重新插拔相机然后检查设备节点的权限ls -l /dev/video*正常的话应该看到类似crw-rw-rw- 1 root plugdev的权限。如果还是crw-rw----且属主是 root说明规则没生效。排查步骤确认规则文件确实在/etc/udev/rules.d/下文件名以.rules结尾。确认sudo udevadm control --reload-rules执行成功没有报错。确认重新插拔了设备或者执行了sudo udevadm trigger。确认用户在 plugdev 组且重新登录过。如果以上都做了还是不行可以临时用 root 跑一下sudo realsense-viewer如果能识别设备那就百分百是权限问题回到 udev 规则继续排查。注意不建议长期用 sudo 跑 realsense-viewer因为 GUI 程序以 root 运行会生成 root 属主的配置文件后面普通用户跑的时候可能因为读不到配置而异常。5. 跑起来之后才会遇到的坑5.1 realsense-viewer 启动报 GL 相关错误第一次运行realsense-viewer可能会遇到这样的报错libGL error: MESA-LOADER: failed to open swrast或者窗口一片黑只有标题栏。这通常是 OpenGL 驱动的问题常见于虚拟机或者没有独立显卡的机器。解决办法分两种情况物理机装一下 mesa 的软件渲染驱动sudo apt install mesa-utils libgl1-mesa-dri然后确认glxinfo | grep OpenGL renderer有输出。虚拟机VMware 或 VirtualBox 里跑需要开启 3D 加速并且装 Guest Additions。即便如此软件渲染下 viewer 的帧率也会很低能看图像但别指望流畅。如果只是想在虚拟机里验证相机能不能识别其实用rs-enumerate-devices和rs-depth这些命令行工具就够了不一定非要跑 GUI。5.2 深度流能开但 RGB 流打不开这个问题的典型表现是viewer 里深度图正常但 RGB 那一栏点开就报错或者一直转圈。原因通常是USB 带宽不够深度流和 RGB 流同时开的时候超了。验证方法在 viewer 里先把深度流关掉只开 RGB如果能开那就是带宽问题。解决办法降低分辨率或帧率比如 RGB 从 1920x1080 降到 1280x720。确认相机插在独立的 USB 3.0 控制器上不和其它高带宽设备共享。检查线材换一根确认支持 USB 3.0 的线。5.3 IMU 数据读不到D435i/D455 用户D435i 和 D455 带 IMU但很多人发现 viewer 里 IMU 那一栏是灰的。这通常是因为IMU 需要单独的固件支持且对 USB 带宽有额外要求。先确认固件版本rs-fw-update -l如果固件版本太老用rs-fw-update -f 固件文件升级。固件文件从官方发布页下载注意选对应型号的。另外IMU 在 USB 2.0 下是完全不可用的必须 USB 3.0。如果lsusb -t显示相机挂在 480M 下IMU 一定读不到。5.4 编译完 viewer 找不到可执行文件前面提过BUILD_GRAPHICAL_EXAMPLES没开的话编译完是没有realsense-viewer的。但还有一种情况开了这个选项cmake 也显示 yes但make install之后which realsense-viewer还是找不到。这是因为 viewer 默认安装在/usr/local/bin而这个路径在某些 Ubuntu 配置下不在普通用户的 PATH 里。检查echo $PATH ls /usr/local/bin | grep realsense如果文件在但 PATH 里没有/usr/local/bin在~/.bashrc里加一行export PATH/usr/local/bin:$PATH然后source ~/.bashrc。6. 几个能省下大量时间的实操经验6.1 用 rs-enumerate-devices 做快速诊断每次改完配置、插拔设备之后别急着开 viewer先用rs-enumerate-devices看一眼。这个命令会列出所有识别到的设备、支持的流配置、固件版本。如果它能看到设备说明底层没问题viewer 的问题就是 GUI 层面的如果它看不到那就是权限或驱动层面的问题。这个二分法能帮你快速定位问题在哪一层。加-c参数可以看到更详细的流配置rs-enumerate-devices -c输出里会列出每个型号支持的分辨率、帧率、格式组合调参的时候很有参考价值。6.2 版本回退比死磕新版本更省事如果你用最新 tag 编译遇到各种奇怪的编译错误别硬扛回退到 v2.50.1 试试。这个版本比较老但对 Ubuntu 20.04 的兼容性经过了大量验证社区里遇到的问题基本都有现成答案。装老版本的代价是少一些新功能但对于能跑起来看图像这个基本需求来说完全够用。回退方法git checkout v2.50.1 rm -rf build mkdir build cd build cmake .. -DCMAKE_BUILD_TYPERelease -DBUILD_EXAMPLEStrue -DBUILD_GRAPHICAL_EXAMPLEStrue make -j$(nproc) sudo make install sudo ldconfig6.3 卸载旧版本要彻底如果你之前用 apt 装过librealsense2再源码编译会冲突。卸载要彻底sudo apt remove --purge librealsense2* realsense-* sudo apt autoremove然后检查/usr/lib/x86_64-linux-gnu/下有没有残留的librealsense2.so有的话手动删掉。不然运行时可能加载到旧版本的库表现就是版本号对不上、功能异常。6.4 记录你的环境信息最后分享一个习惯装完之后把关键环境信息记下来包括内核版本、librealsense 版本、固件版本、USB 连接方式。后面如果换机器或者重装系统直接照着这份记录来能省掉大量重复排查的时间。uname -r rs-enumerate-devices --version rs-fw-update -l lsusb -t | grep -A2 Video这四行输出基本涵盖了所有关键信息。我自己的记录里还加了一行dpkg -l | grep -i realsense用来确认有没有 apt 残留。整套流程走下来顺利的话半小时内能搞定遇到坑的话可能折腾一两个小时。但只要理解了每个环节的作用排查起来就有方向不会像无头苍蝇一样乱试。核心思路就一句话先确认内核和 USB 没问题再确认库编译安装没问题最后确认 udev 权限没问题这三层依次排查基本没有解决不了的。
