企业官网建设流程全解析

1. 为什么 RealSense 在 Ubuntu 20.04 上总装不顺

RealSense 深度相机在机器人、三维重建、视觉抓取这些方向里出镜率极高，D435i、D455、L515 几乎是实验室和创业团队的标配。但真正上手的人都有一个共同感受：相机本身没问题，卡住人的永远是驱动和查看工具。realsense-viewer是官方 librealsense 自带的图形化工具，能实时看深度流、彩色流、IMU 数据，还能直接调曝光、增益、激光功率，是验证相机是否正常工作的第一道关卡。可它在 Ubuntu 20.04 上的安装过程，坑多到能写一篇长文。

我前后在五六台机器上装过这套东西，有物理机、有 VMware 虚拟机、有 RK3588 这类 ARM 平台，也踩过内核版本不匹配、依赖缺失、权限不足、ROS 包冲突这些典型问题。这篇就把整个流程从头到尾捋一遍，重点讲清楚每一步为什么这么做，以及出问题的时候怎么排查。不管你是刚拿到相机的新手，还是已经在跑 ROS 但 viewer 打不开的老手，应该都能从里面找到对你有用的部分。

需要先说明一点：本文所有操作都基于 Ubuntu 20.04 + ROS Noetic 这个组合，这也是目前最稳、资料最全的一套环境。如果你用的是 Ubuntu 22.04 或者 ROS 2 Humble，大方向一致，但包名和部分依赖会有差异，我会在对应位置标注出来。

2. 安装前的环境确认与依赖梳理

2.1 先搞清楚你的相机型号和固件版本

动手装驱动之前，先把相机插上 USB 3.0 口，用lsusb看一眼设备有没有被系统识别：

lsusb | grep -i intel

正常应该能看到类似Intel Corp.开头的设备。如果什么都看不到，先别急着装驱动，问题可能出在 USB 口或者线材上。RealSense 对供电和带宽要求比较高，必须插在原生 USB 3.0 口上，前面板的扩展口、USB Hub 经常带不动，表现为设备时有时无或者直接不识别。

确认识别之后，记录下你的相机型号。D435i 和 D455 带 IMU，L515 是激光雷达方案，不同型号对 librealsense 版本的要求不一样。L515 必须用 2.50 以上的版本，老版本根本不支持，这一点很多人不知道，装完发现设备打不开就是版本问题。

固件版本也建议顺手查一下。如果相机是很久没用的库存货，固件可能停留在出厂版本，和新驱动配合会有兼容性问题。固件更新工具在官方 SDK 里自带，后面会提到。

2.2 Ubuntu 20.04 的内核版本是个隐藏变量

这是最容易被忽略的一点。librealsense 需要编译内核模块（主要是uvcvideo的补丁版本和hid相关模块），而内核版本直接决定了编译能不能过。Ubuntu 20.04 默认内核是 5.4，这个版本兼容性最好。但如果你做过系统更新，内核可能已经升到 5.15 甚至更高，这时候编译就容易报错。

查一下当前内核：

uname -r

如果是 5.4.x，恭喜你，一路顺畅。如果是 5.8 以上，建议在编译 librealsense 时加上-DFORCE_RSUSB_BACKEND=ON这个选项，走 USB 后端而不是内核补丁路径，能绕开大部分内核模块编译问题。代价是性能略低一点点，但稳定性反而更好，实测在虚拟机和 ARM 平台上这个选项几乎是必加的。

提示：虚拟机里装 RealSense 驱动，强烈建议直接用 RSUSB 后端。VMware 和 VirtualBox 对 USB 直通的支持都不算完美，走内核补丁路径大概率失败。

2.3 依赖包一次性装齐，别等报错再补

很多人习惯边装边补依赖，结果编译到一半报错，前面的进度全废。我的做法是先把所有依赖一次性装完，再开始编译。下面这串命令是我反复验证过的，Ubuntu 20.04 上直接复制执行：

sudo apt-get update sudo apt-get install -y git cmake build-essential libssl-dev libusb-1.0-0-dev \ pkg-config libgtk-3-dev libglfw3-dev libgl1-mesa-dev libglu1-mesa-dev \ libudev-dev libv4l-dev libavcodec-dev libavformat-dev libswscale-dev \ python3-dev python3-numpy

这里面几个包值得单独说一下。libusb-1.0-0-dev是 USB 通信的基础，缺了它编译直接失败；libgtk-3-dev是 realsense-viewer 图形界面的依赖，缺了它 viewer 根本编译不出来；libglfw3-dev和libgl1-mesa-dev负责 OpenGL 渲染，虚拟机里如果没装显卡驱动，这两个包就是救命稻草。

如果你还要跑 ROS 相关的 realsense-ros 包，那ros-noetic-realsense2-camera和ros-noetic-realsense2-description也建议一起装上，后面做标定和仿真会用到。

3. librealsense 源码编译的完整实操

3.1 为什么推荐源码编译而不是 apt 安装

Ubuntu 的 apt 源里其实有librealsense2这个包，一条命令就能装。但我不推荐，原因有三个：第一，apt 版本通常比较老，新相机型号支持不全；第二，apt 版本不带 realsense-viewer，你还得单独装；第三，出问题的时候你根本不知道它装到哪了，排查起来很痛苦。

源码编译虽然麻烦一点，但版本可控、路径清晰、出问题能定位。而且编译过程本身也就十几分钟，值得。

3.2 拉取源码与版本选择

git clone https://github.com/IntelRealSense/librealsense.git cd librealsense git checkout v2.54.2

版本选择有讲究。v2.54.2 是我在 Ubuntu 20.04 上验证过最稳的一个版本，对 D435i、D455、L515 支持都完整，和 ROS Noetic 的兼容性也好。如果你用的是更新的相机比如 D457，那得用 v2.55 以上。不建议直接用 master 分支，开发版经常有未修复的 bug，编译失败率明显更高。

3.3 打内核补丁这一步到底要不要做

官方文档会让你先跑scripts/patch-realsense-ubuntu-lts.sh打内核补丁。这个脚本的作用是给uvcvideo驱动打补丁，让系统原生支持 RealSense 的元数据流。打补丁的好处是性能更好、延迟更低，坏处是一旦内核升级补丁就失效，而且打补丁过程本身容易失败。

我的建议是：物理机 + 内核 5.4，可以打；虚拟机、ARM 平台、内核 5.8 以上，直接跳过，用 RSUSB 后端。判断标准很简单，如果你不确定自己需不需要，那就是不需要。

跳过补丁的话，编译时加这个参数：

mkdir build && cd build cmake .. -DFORCE_RSUSB_BACKEND=ON -DBUILD_PYTHON_BINDINGS=ON \ -DCMAKE_BUILD_TYPE=Release -DBUILD_EXAMPLES=ON

BUILD_EXAMPLES=ON这个选项很关键，realsense-viewer 就在 examples 里面，不开这个选项编译完是没有 viewer 的。BUILD_PYTHON_BINDINGS=ON是给后面用 Python 做二次开发准备的，不需要可以去掉。

3.4 编译与安装

make -j$(nproc) sudo make install sudo ldconfig

make -j$(nproc)是并行编译，用满所有 CPU 核心，能快不少。但如果你内存比较小（比如虚拟机只给了 4G），并行编译可能因为内存不足被 kill，这时候改成make -j2稳一点。

sudo ldconfig这一步千万别漏，它的作用是刷新动态链接库缓存，不做的话运行 viewer 会报error while loading shared libraries，很多人卡在这里以为是装失败了，其实就是少跑了一条命令。

3.5 udev 规则配置，解决权限问题

装完之后直接运行realsense-viewer，大概率会提示权限不足或者设备打不开。这是因为普通用户没有 USB 设备的访问权限，需要配置 udev 规则：

sudo cp config/99-realsense-libusb.rules /etc/udev/rules.d/ sudo udevadm control --reload-rules && sudo udevadm trigger

配完之后必须重新插拔相机，规则才会生效。这一步是新手最容易忘的，配了规则不插拔，然后说没用，其实规则已经生效了只是设备还没重新枚举。

4. realsense-viewer 启动与功能验证

4.1 第一次启动该看什么

命令行直接敲：

realsense-viewer

如果一切正常，会弹出一个图形界面，左侧是设备列表，中间是各个传感器的开关。第一次打开建议按这个顺序验证：

1. 先开 Stereo Module，看深度图有没有出来，画面是不是正常
2. 再开 RGB Camera，看彩色流
3. 如果是 D435i 或 D455，最后开 Motion Module，看 IMU 数据

深度图正常的表现是：近处物体偏红/黄，远处偏蓝，整体平滑没有大面积黑洞。如果深度图全是噪点或者大片黑色，通常是曝光或者激光功率设置问题，在右侧控制面板里调一下 Laser Power 和 Exposure 就能改善。

4.2 关键参数怎么调

viewer 右侧的控制面板里参数很多，新手容易懵。我挑几个最常用的说：

调参的时候有个技巧：先开自动曝光让相机自己找基准，然后再切手动微调。直接上手动很容易调过头，画面一片白或者一片黑。

4.3 录制与回放数据

viewer 右上角有个录制按钮，能把当前所有流录成.bag文件。这个功能在做算法调试的时候特别有用，一次录制，反复回放，不用每次都把相机架起来。回放的时候直接拖 bag 文件进 viewer 就行，所有参数都能重新调，相当于一个离线实验室。

录 bag 有个注意点：文件会很大，深度流 + 彩色流 + IMU 全开的话，一分钟大概 1-2G。建议按需录制，只开需要的流，录制时间也别太长。

5. 常见报错与排查速查表

5.1 编译阶段报错

5.2 运行阶段报错

5.3 几个我踩过的坑

坑一：虚拟机 USB 直通不稳定。VMware 里把相机直通给虚拟机，经常出现设备识别了但一开流就断的情况。解决办法是在虚拟机设置里把 USB 兼容性改成 3.1，并且关掉主机的 USB 节能选项。

坑二：ROS 包和源码版本冲突。如果你之前 apt 装过ros-noetic-realsense2-camera，它可能带了一个老版本的 librealsense，和你源码编译的版本打架。排查方法是ldd $(which realsense-viewer)看它链接的是哪个库，如果指向/opt/ros/下面的，就得调整环境变量优先级。

坑三：多相机同时用。同时插两个 RealSense，viewer 默认只显示一个。需要在启动时指定序列号，或者用rs-enumerate-devices先列出所有设备，再针对性打开。

6. 和 ROS 打通后的进阶玩法

6.1 realsense-ros 包的安装与配置

viewer 验证通过之后，下一步通常就是接 ROS。Ubuntu 20.04 + ROS Noetic 的组合下，安装很简单：

sudo apt install ros-noetic-realsense2-camera ros-noetic-realsense2-description

启动相机节点：

roslaunch realsense2_camera rs_camera.launch

然后在另一个终端rostopic list，应该能看到/camera/color/image_raw、/camera/depth/image_rect_raw这些话题。如果话题出不来，八成是相机被 viewer 占用了，viewer 和 ROS 节点不能同时开，会抢设备。

6.2 标定与点云生成

相机跑起来之后，做视觉任务基本都要标定。内参标定用camera_calibration包，外参标定（比如手眼标定）用easy_handeye或者moveit自带的标定工具。标定板建议用 6x9 的棋盘格，打印出来贴在硬板上，平整度很重要，翘边的标定板标出来的参数全是错的。

点云生成直接用rs_camera.launch加参数：

roslaunch realsense2_camera rs_camera.launch filters:=pointcloud

然后在 RViz 里加 PointCloud2 显示，话题选/camera/depth/color/points。点云质量受深度图质量影响很大，深度图调好了点云才干净。

6.3 在机械臂和移动平台上的应用

RealSense 在机械臂抓取里的典型用法是：相机固定在末端或者固定在外部，先做手眼标定，然后深度图转点云，点云做分割和位姿估计，最后把位姿发给 MoveIt 做运动规划。这条链路里最容易出问题的是标定精度，标定误差 1 厘米，抓取就可能差好几厘米。

移动平台上的用法更简单一些，主要是做避障和建图。D435i 的 IMU 可以和轮式里程计做融合，跑 VINS 或者 LIO-SAM 这类算法。不过要注意，RealSense 的 IMU 频率不高（200Hz 左右），做高动态场景会不够用，静态或者低速场景没问题。

7. 我个人的几条实操建议

装这套东西前后折腾了这么多次，有几个体会是文档里不会写的，分享出来给后来人省点时间。

第一，环境干净比什么都重要。如果你之前装过其他版本的 librealsense，先彻底卸载干净再装新的。残留的库文件和环境变量是很多诡异问题的根源，/usr/local/lib下面翻一翻，有旧的librealsense2.so就删掉。

第二，虚拟机只适合学习和验证，不适合做实际项目。USB 直通的稳定性、显卡渲染的性能，都撑不住长时间运行。真要做项目，物理机或者 ARM 板子才是正路。

第三，固件更新别偷懒。新相机到手第一件事就是更新固件，很多莫名其妙的问题（IMU 不动、深度跳变、设备掉线）更新完固件就好了。更新工具在 librealsense 的tools/fw-update目录下，编译完就有。

第四，遇到问题先看日志。viewer 启动时加-v参数能看到详细日志，ROS 节点用roslaunch ... --screen能看到实时输出。大部分报错信息其实说得很清楚，只是很多人不看。

最后再提一句，如果你用的是鱼香 ROS 这类一键安装脚本，装 ROS 本身确实省事，但RealSense 驱动它管不了，还是得按上面的流程手动来。脚本能帮你省的是 ROS 环境配置的时间，相机这块该踩的坑一个都少不了。