第一次在 Ubuntu20.04 下鼓捣 Intel RealSense 深度相机的人大概率会经历这个场景SDK 装好了realsense-viewer 也能看到彩色图和深度图了结果一到 realsense-ros 就各种报错找不到设备、链接库版本对不上、launch 文件一跑就崩。这种情况我在自己机器上遇到过至少三轮所以这篇不是从官方 README 搬运的步骤而是把 Ubuntu20.04 下从 realsense-viewer 到 realsense-ros 的整条链路拆开讲清楚。目标读者是刚拿到 D415/D435/D435i 这类相机、准备接入 ROS 做开发的朋友也包括那些已经装到一半、被各种玄学报错卡住的老哥。文章会把每一步为什么要这么做的理由也写出来不只是甩命令。1. 开工前的环境体检内核、USB 与依赖工具链很多安装失败其实不是装的过程有问题而是环境本身就有隐患。所以在碰源码之前先把系统状态看清楚。这个体检大概花五分钟但能帮你省掉后面好几小时的排查时间。1.1 内核版本与系统发行版确认首先确认系统确实是 Ubuntu 20.04并且看看内核版本。打开终端执行lsb_release -a uname -rUbuntu 20.04 的默认内核一般是 5.4 或者 5.8也有不少同学手动升级到 5.11 甚至 5.15 的。librealsense 从 2.50 版本开始对 Ubuntu 20.04 这类 LTS 系统的官方支持已经很完善不再要求给内核的 uvcvideo 模块打补丁。这一点和网上很多老教程不一样——老教程里第一步就是运行./scripts/patch-realsense-ubuntu-lts.sh这个操作在新版本里已经被移除也不需要再去做。如果你是在老版本 SDK比如 2.43 之前环境下装过补丁那升级到新 SDK 之前最好确认一下补丁是否还残留因为官方文档明确说明新版已经断了这条路。一般用户没必要碰内核补丁直接跳过这一步。1.2 用 lsusb 验证 USB 链路是否正常RealSense 相机的本质是一个 UVC 摄像头加一系列传感器所以安装前先确认系统能不能在 USB 层面发现它。执行lsusb | grep -i 8086常见型号的 USB ID 大概是这些型号USB IDD415 / D435 / D435i8086:0b3aL5158086:0b64D4558086:0b5c如果lsusb能看到 8086 开头的设备说明 USB 链路正常相机供电和硬件基本没问题。要是你的相机插上去完全没反应先别急着装软件换个 USB 口、换根线试试。RealSense 对线材和接口比较挑剔USB 2.0 口虽然也能识别但带宽不足会导致后面跑点云各种掉帧所以最好插在蓝色的 USB 3.0 接口上。这里有个细节容易被忽略如果你是在虚拟机里跑 UbuntuUSB 直通配置不好lsusb要么看不到设备要么只显示一个通用的 USB 摄像头设备名。这种情况会严重影响后续调试建议直接装双系统或者物理机别在虚拟机上折腾 RealSense 的 ROS 集成。另外如果你的 USB 设备接在扩展坞或者劣质 HUB 上低负载下可能没问题一旦跑大流量就容易掉线这也是个隐藏雷区一开始就避开最好。1.3 装齐编译工具链和第三方依赖librealsense 源码编译需要一整套依赖。别偷懒一次性装齐不然编译到一半报错再回头补更浪费时间sudo apt update sudo apt 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这里面最容易漏的是libglfw3-dev。它是 realsense-viewer 图形界面依赖的窗口库如果没装cmake 会提示找不到 GLFW然后你就得倒回去重新编译。另外如果你计划用 Python 调用 pyrealsense2还要加libpython3-dev不过这篇主要是 C 和 ROS 方向Python 绑定先不展开。2. librealsense 源码编译三种安装方式里为什么选它librealsense 的安装方式大致有三种Intel 官方 apt 仓库安装、预编译二进制包、源码编译。我强烈推荐第三种下面说清楚理由。2.1 三种安装方式对比与我的选型逻辑Intel 提供了 apt 源理论上apt install librealsense2-dev一行就能解决但实际情况常常不是这样。apt 仓库里包含的 SDK 版本和 realsense-ros 的 dev 分支之间有时候会出现版本错位而且 Ubuntu 20.04 系统自带的 ROS 源、相机固件升级工具等都有自己的版本节奏一旦某个小版本匹配不上报错信息会非常抽象排查起来心情极其糟糕。预编译二进制包同理适合只是临时跑个 demo 验证硬件不适合作为 ROS 集成的基础。源码编译看起来麻烦但好处有三可以锁定一个明确的 SDK 版本后续 realsense-ros 编译时版本对应关系清晰编译过程会暴露很多环境和依赖问题等于提前做了一次系统体检cmake 的开关可以按需调整比如是否编译示例、是否开启 Python 绑定。2.2 源码拉取与编译参数选择git clone https://github.com/IntelRealSense/librealsense.git cd librealsense git checkout v2.54.2 mkdir build cd build cmake ../ -DCMAKE_BUILD_TYPERelease -DBUILD_EXAMPLEStrue make -j$(nproc) sudo make install关于git checkout那一步我建议你选中一个官方稳定版本比如 v2.54.2 或者你手头文档配套的版本不要直接留在 master 分支。master 分支往往比 realsense-ros 的 ros1-legacy 分支新不少两者之间偶尔会有接口变动这种不一致是最难排查的坑之一。-DBUILD_EXAMPLEStrue会编译 realsense-viewer、rs-enumerate-devices 等一系列工具这正是我们需要的。不建议为了省时间关掉它因为后面的调试阶段这些工具会反复用到。编译时make -j$(nproc)会调用你机器所有 CPU 核心并行编译如果你的内存小于 8GB建议改成make -j4避免编译中途内存耗尽直接被 OOM killer 干掉。2.3 udev 规则配置权限避免每次调试都要 sudo编译安装完之后千万别忘了这一步。RealSense 相机要获得非 root 用户的访问权限必须安装官方提供的 udev 规则文件cd ~/librealsense sudo cp config/99-realsense-libusb.rules /etc/udev/rules.d/ sudo udevadm control --reload-rules sudo udevadm trigger sudo usermod -a -G plugdev $USER然后重新登录一次或者重启让plugdev用户组权限生效。这里有个非常经典的坑很多人不执行这条usermod导致普通用户运行 realsense-viewer 时一直报 No device connected而加sudo又能正常运行。如果你遇到这个现象第一个要去查的就是 udev 规则和用户组权限而不是 SDK 本身。3. realsense-viewer装完先别急着上 ROS3.1 启动 viewer 并认识它的界面编译安装完成后终端直接输入命令即可打开图形界面realsense-viewer如果提示找不到命令可以到/usr/local/bin/realsense-viewer确认或者回到源码 build 目录下运行./examples/viewer/realsense-viewer。viewer 的界面左侧是设备列表和相机参数中间是各个传感器的预览窗口。顶部有 Depth、RGB、IMU 等开关打开之后能看到实时画面。这一阶段的核心目的不是玩而是确认相机硬件、SDK、USB 链路三者都正常。viewer 里还有个很实用的功能左侧 Storage 区域的 Record 按钮可以录制.bag格式的原始数据包录完之后即使相机不在手边也能用rosbag play回放这些数据配合 realsense-ros 继续开发调试。这一点对做算法验证帮助特别大很多场景下不需要反复接相机也能迭代代码。3.2 查看固件版本并按需升级在 viewer 左侧的 Device 信息里能看到 Firmware Version。如果固件版本太旧部分新特性比如某些对齐模式可能不可用甚至导致 ROS 节点运行异常。升级固件需要先从 Intel 官方渠道下载对应相机型号的.bin固件文件然后执行rs-fw-update -f Signed_Image_UVC_5_13_0_50.bin这个工具在编译好的 build 目录下也可能已经安装到了系统路径。升级过程中千万不能断电或者拔 USB 线。RealSense 固件升级失败的情况我遇到过好在没有变砖重新刷一次就能恢复但整个过程还是让人手心冒汗。所以操作之前确认电池供电稳定、USB 线不要松动。3.3 用 viewer 做一次完整的传感器自检我习惯在接 ROS 之前先在 viewer 里把所有传感器过一遍Depth 打开用手在相机前晃动深度图应该能明显看到手部轮廓和远近变化RGB 画面正常颜色没有严重偏色如果是 D435i 这类带 IMU 的型号打开 Gyro 和 Accel能看到三轴数据在不断跳动打开 3D 模式能看到点云实时渲染这就是后面 ROS 里 PointCloud2 话题的数据来源。这些自检项目都通过之后基本可以断定硬件和 SDK 层没有问题。接下来再出问题就是 ROS 集成层的事了。4. realsense-ros 编译分支选择是第一个大坑4.1 ROS 工作空间的创建假设你已经装好了 ROS Noetic。如果没有先用官方流程装好基础版。然后创建 catkin 工作空间mkdir -p ~/catkin_ws/src cd ~/catkin_ws/src catkin_init_workspace cd ~/catkin_ws catkin_make这块比较基础简单带过。真正容易踩坑的是下面的分支选择。4.2 别直接 clone 默认分支ros1-legacy 才是正解这是我在这个项目上踩过最深的一次坑。当时我直接执行git clone https://github.com/IntelRealSense/realsense-ros.git然后catkin_make结果编译到一半报出一堆和 ROS2 相关的错误。后来才知道realsense-ros 仓库的默认分支master早已转向 ROS2要和 ROS1 Noetic 配套使用必须切换到ros1-legacy分支cd ~/catkin_ws/src git clone https://github.com/IntelRealSense/realsense-ros.git cd realsense-ros git checkout ros1-legacy切完分支再回去编译cd ~/catkin_ws catkin_make如果编译过程中报错提示找不到ddynamic_reconfigure说明缺了编译期的动态参数配置库安装一下再继续sudo apt install ros-noetic-ddynamic-reconfigure source ~/catkin_ws/devel/setup.bash注意每次编译完新工作空间后都要 source 当前工作空间的 setup.bash。我习惯把它写进~/.bashrc但如果你同时装了多个 ROS 工作空间source 顺序会影响功能包查找的优先级这是个入门阶段不太容易察觉的坑。4.3 启动 launch 文件并确认话题列表编译好之后最基础的一步是启动相机驱动节点roslaunch realsense2_camera rs_camera.launch如果一切正常终端会刷出相机型号、序列号、固件版本等信息紧接着你可以另开一个终端输入rostopic list | grep /camera/正常情况下应该能看到/camera/color/image_raw、/camera/depth/image_rect_raw、/camera/depth/color/points等话题。如果看到这些说明 realsense-ros 已经和底层 SDK 打通了。如果在这个阶段报librealsense2.so找不到多半是库里装的 SDK 位置不在默认搜索路径里。源码安装默认是/usr/local/lib一般没问题如果你自定义过安装路径需要设置export LD_LIBRARY_PATH/your/custom/path:$LD_LIBRARY_PATH。还有一次我在 catkin_make 过程中遇到 OpenCV 版本冲突的提示因为工作空间里另一个包装了更高版本的 OpenCV。这种情况一般是在 launch 或者 CMakeLists 里明确指定需要的 OpenCV 版本或者干脆把那个冲突包移出工作空间一步步隔离排查。4.4 launch 文件里最常用的几个启动参数rs_camera.launch 默认只打开深度和彩色流。实际开发中我们经常需要调整几个参数比如让深度图与彩色图对齐roslaunch realsense2_camera rs_camera.launch align_depth:true如果你要 IMU 数据D435i / L515用roslaunch realsense2_camera rs_camera.launch enable_gyro:true enable_accel:true unite_imu_method:1unite_imu_method:1会把 gyro 和 accel 合并到同一个/camera/imu话题下方便后续处理。这个配置我一开始没加结果两个话题各发各的时间戳对齐问题烦了很久。5. RViz 可视化和动态调参把点云真正显示出来5.1 从话题到画面的完整链路驱动跑起来之后数据已经在 ROS 话题里流动了但没可视化的话你很难直观判断这些数据到底对不对。我一般用 RViz 来看rosrun rviz rviz打开 RViz 后第一件事是把左上角 Fixed Frame 改成camera_link或者camera_depth_frame否则画面会因为坐标系找不到而黑屏。然后点击 Add - By topic选择/camera/depth/color/points的 PointCloud2 话题就能看到深度相机的点云了。这里我要特别强调一个新手最容易困惑的点RViz 默认把点云渲染的 Size 设得非常小如果你添加了点云话题但画面上只有稀疏的几个点不要慌在 PointCloud2 的 Size 参数里把数值调大到 0.02 到 0.05 试试。这不是 bug只是显示参数的问题。5.2 深度与彩色对齐点云效果会好很多刚才提到align_depth:true这个参数的影响在点云可视化上体现得非常明显。对齐之后深度图和彩色图的像素坐标一一对应点云中每个点的颜色都来自 RGB 图像看起来就是一幅真正意义上的彩色三维模型不对齐的话点云和彩色画面常会发现色彩错位、偏移。在跑 SLAM 或者做目标检测的后期处理时对齐几乎是必选项。代价是轻微增加 CPU 占用但对 D435 这类入门相机来说完全可接受。5.3 用 rqt_reconfigure 实时调参数不重启节点相机的一些参数比如自动曝光、白平衡、深度范围会直接影响图像质量。调试阶段如果每调一个参数就重启一次节点效率太低。ROS 提供了动态参数配置工具rosrun rqt_reconfigure rqt_reconfigure界面里能看到 realsense2_camera 的所有可调参数auto_exposure、color_white_balance、depth_units等等。改完马上生效这个工具在项目调试期几乎是每天必开的。不过我实测过这里调好的参数只是临时生效节点重启后就恢复默认。所以如果你调出了一组效果很好的参数最后记得把关键参数写回到 launch 文件里这样每次启动都是稳定的状态。6. 常见问题排查记录这些坑我基本都踩过6.1 权限问题普通用户找不到设备、sudo 能跑这个是 RealSense 相关论坛里出现频率最高的一个问题。现象是lsusb能看到设备sudo realsense-viewer能打开画面但普通用户运行就报No device connected。根源就是 udev 规则没生效或者用户不在plugdev组里。按 2.3 节的命令重新配置一遍然后确认id命令的输出里包含plugdev。注意如果id命令输出里已经有plugdev但普通用户仍访问不了设备重新插拔一次 USB 比反复重启系统更有效。如果加了组还是不行重新登录或者重启一次别偷懒。6.2 多相机同时接入用 serial_no 区分同一台机器上接两台 RealSense 时默认的 launch 会冲突因为话题名和设备选择逻辑都一样。我的解决办法是给每台相机指定序列号roslaunch realsense2_camera rs_camera.launch serial_no:123456789 camera_name:cam1序列号可以从rs-enumerate-devices的输出里找到。同时注意camera_name要设置成不同的值否则两套话题会重名导致下游节点数据错乱。6.3 画面卡顿、点云断层检查 USB 带宽和流参数点云断裂、深度图掉帧最常见的原因不是相机坏了而是 USB 带宽不够。RealSense 在 1280x720、30FPS 的分辨率下跑了深度、彩色、红外三路流叠加点云渲染USB 3.0 的真实吞吐压力非常大。排查顺序确认插在 USB 3.0 蓝色接口上并且线材质量可靠在 launch 或 viewer 里降低分辨率到 640x480把帧率从 30FPS 降到 15FPS如果不需要红外流关闭它。我从第一次拿到 D435 到配置稳定差不多把分辨率从默认降到 848x480、15FPS才在多个不同场景下都跑得比较稳。6.4 版本不匹配librealsense 和 realsense-ros 的对应关系SDK 和 ROS 包之间如果版本跨度太大会出现各种解释不清的报错比如节点启动后图像话题不发数据、发布一秒就断流。我的建议是librealsense 选一个官方稳定版比如 v2.54.2realsense-ros 用 ros1-legacy 分支的最新稳定提交。如果你以后重新拉取了更新版本的 SDK记得把 realsense-ros 的源码也同步拉取最新然后重新catkin_make。最后分享一个我自己的调试小习惯每次升级内核或者重装系统之后不要急着跑项目代码先执行lsusb看一眼相机是否还在再realsense-viewer看画面是否正常。这套快速检查只需要一分钟但能帮你把“系统环境变化”和“你自己的代码问题”这两件事彻底隔离开。很多看起来莫名其妙的问题最后都出在环境上而不是相机上。