说出来你可能不信一个号称“只 clone 就能编译”的激光雷达 ROS2 驱动让我在编译阶段就折腾了两个晚上。拿到 Mid-360 那天我原本的计划是半小时跑通装依赖、克隆仓库、colcon build、启动 RViz 看点云。结果是colcon build那一步反复报错要么找不到livox_sdk.h要么环境变量没生效甚至同样的代码在另一台 Ubuntu 上行为都不一样。后来我才意识到Livox ROS Driver2 的编译方式跟大多数 ROS 包完全是两码事它既要依赖独立的 Livox-SDK2又要靠ROS_VERSION环境变量分流 ROS1/ROS2 两套构建逻辑任何一步没对齐都会翻车。这篇文章就是冲着“从零到一”这四个字来的。我会按照实际踩坑的顺序把系统版本选择、SDK 编译、驱动编译、报错排查、雷达连接配置这些环节全部拆开讲顺便把那些官方 README 里没写清楚、但对新手极其关键的细节补齐。如果你正准备在 Ubuntu 上编译部署 Livox ROS Driver2不管接下来要接的是 Mid-360、Avia 还是 HAP这篇文章应该能帮你把整个流程控制在半小时以内。1. 搭建前先定基线Ubuntu版本、ROS发行版与网络规划的取舍1.1 为什么建议用 Ubuntu 22.04 ROS 2 Humble很多人在第一步就栽了跟头因为直接用自己的主力电脑开干系统版本五花八门。我实测下来当前阶段最省心的组合是Ubuntu 22.04 ROS 2 Humble。这个组合能跑通也有足够的社区案例可以参考出问题搜一下基本都是同款。Ubuntu 20.04 ROS 2 Foxy 也能编但没那么推荐。Foxy 在 2023 年就已经停止维护了而且因为你可能会同时装 OpenCV、PCL、FastDDS 这类依赖20.04 自带的 CMake 版本偏低编译过程中容易触发一些跟版本有关的隐性报错。后面讲编译报错的时候你会看到很多问题归根结底不是代码的问题是你底层工具链太老。如果你是 ROS 1 的老熟人用 Ubuntu 20.04 Noetic 也能走通 Livox ROS Driver2 的 ROS1 编译路径但我的建议是别挣扎了直接切 ROS 2。Livox 驱动对 ROS2 的支持已经很成熟launch 文件、参数配置、话题命名都按 ROS2 的习惯设计好了硬要在 ROS1 里等值替代反而要多踩很多坑。1.2 编译前必装的系统工具在 clone 任何代码之前先把基础工具补齐。我见过有人用了半天排查编译错误最后发现是build-essential都没装。以下是我在一台干净 Ubuntu 22.04 上验证过的安装命令sudo apt update sudo apt install -y build-essential cmake git python3-colcon-common-extensions如果你打算用 ROS2 的方式编译还需要保证/opt/ros/humble目录存在并且已经 source 过。通常安装 ROS2 Humble 时已经带上了ament_cmake、rclcpp、sensor_msgs这些核心包不需要额外处理。如果用的是精简安装编译时很有可能会报找不到ament_cmake那就需要补装sudo apt install -y ros-humble-ament-cmake ros-humble-rclcpp ros-humble-sensor-msgs ros-humble-tf2-roscolcon这个工具也容易漏。很多教程默认你有完整的 ROS2 桌面版环境实际上如果你之前只装过ros-humble-ros-base不一定有colcon。装不上就直接sudo apt install python3-colcon-common-extensions一分钟解决。1.3 网络规划雷达的默认 IP 与主机网卡的关系编译部署只是前半场后面连雷达时网络配置会让人头疼。Livox 雷达出厂默认是一个静态 IP常见的是192.168.1.100这段具体要看型号。驱动通过 UDP 广播在局域网里发现雷达所以你的主机网卡必须和雷达在同一个网段否则驱动会一直处于初始化或连接中的状态。这里有两个选择一是直接用一根网线把雷达和主机的千兆网卡连起来手动给网卡配置一个同网段 IP比如192.168.1.50子网掩码255.255.255.0二是通过路由器/交换机把它们放到同一个局域网。无论哪种方式建议先把防火墙对 UDP 的限制关掉或者至少保证 6000-7000 端口不被拦截这一条后面部署章节还会展开。2. 第一道坎Livox-SDK2编译安装的细节2.1 Livox-SDK2 和 livox_ros_driver2 是两个独立仓库这是很多人首战失利的原因把livox_ros_driver2当成一个用colcon build就能独立编出来的 ROS 包。实际不是这样。ROS 驱动只是一个上层封装它下面还压着一层 Livox SDK2负责跟雷达的通信协议、数据解析、时间同步这些底层活儿。你要先编译安装好 SDK2ROS 驱动编译时才能找到头文件和动态库。这两个仓库的关系可以理解成SDK2 是发动机ROS Driver2 是车身。车身造得再漂亮没有发动机也跑不起来。官方仓库地址分别是Livox-SDK/Livox-SDK2和Livox-SDK/livox_ros_driver2两个都建议 clone 到同一个工作目录下方便管理。2.2 Livox-SDK2 的编译安装过程与参数说明SDK2 的编译不需要 ROS 环境底层依赖也不多直接按标准 CMake 流程走git clone https://github.com/Livox-SDK/Livox-SDK2.git cd Livox-SDK2 mkdir build cd build cmake .. make -j$(nproc) sudo make install默认安装路径是/usr/local头文件会放到/usr/local/include动态库放到/usr/local/lib。这一步如果顺利你可以检查一下动态库是否被系统正确识别sudo ldconfig ls /usr/local/lib | grep livox这里有一个值得理解的细节sudo make install为什么要执行因为 ROS 驱动编译时依赖 SDK2 的 include 路径和库文件如果只make而不install驱动就找不到对应的头文件。很多新手在 SDK2 目录里编译成功就以为完成了结果回到驱动这边直接报livox_sdk.h: No such file or directory根源就在这。2.3 如果你不想装到系统目录make install装到/usr/local是官方默认行为但对部分人来说系统目录越来越脏是一件很难受的事。如果你想控制在用户目录下可以这样安装cmake .. -DCMAKE_INSTALL_PREFIX$HOME/livox_install make -j$(nproc) make install但要注意这种自定义路径后面在编译 ROS 驱动时不仅要设置LIVOX_SDK2环境变量还可能要额外指定动态库路径。实际测试下来对新手来说不建议自定义安装路径能省一事是一事。3. 驱动编译的入口分支、环境变量与构建系统选择3.1 同一个仓库靠 ROS_VERSION 分流 ROS1 和 ROS2livox_ros_driver2特别的地方在于它用一套代码同时兼容 ROS1 和 ROS2。具体实现是编译系统里根据环境变量ROS_VERSION的值走不同的分支逻辑。ROS_VERSION1走 ROS1 的 catkin 路径ROS_VERSION2走 ROS2 的 ament/colcon 路径。这个设计的出发点是降低维护成本但副作用也很明显如果你忘了设置ROS_VERSION或者设错了驱动会走完全不同的编译路径报出的错误信息也很迷惑。我的建议是编译前先用echo $ROS_VERSION确认一下当前值如果没输出说明根本没设置。命令如下export ROS_VERSION2在 ROS1 场景下这个变量本身没啥用因为 ROS1 环境的 setup.bash 已经帮你把很多东西配置好了但 ROS2 环境下必须手动指定。凡是编译过程中出现跟 ROS 头文件、rclcpp、ament 相关但看起来莫名其妙的报错第一个要排查的就是这个变量。3.2 分支选择master 和 ros2 的差别clone 下来的仓库默认在 master 分支。但早期版本的livox_ros_driver2ROS2 支持是放在独立分支里的比如ros2分支。现在的代码主线已经逐步统一了但稳妥起见拿到仓库后第一件事是看 README 说明cd livox_ros_driver2 git branch -a如果发现当前分支和你要用的 ROS 版本不匹配比如你明明要编译 ROS2 版当前却停在只支持 ROS1 的旧分支后面所有报错都会变得无迹可寻。切换分支用git checkout ros23.3 ROS_PACKAGE_PATH 的作用这个环境变量在 ROS1 时代很常见到了 ROS2 很多人对它没什么概念。但livox_ros_driver2的 CMake 逻辑依然依赖它来找包。官方 README 给的编译步骤里明确要求设置export ROS_PACKAGE_PATH$PWD:$ROS_PACKAGE_PATH这行命令的意思是把你当前所在的驱动目录加到 ROS 的包搜索路径里驱动内部的 CMake 脚本会通过这个路径去定位package.xml和其他资源文件。漏了这一步可能出现包的依赖关系能解析但构建时找不到源文件目录的情况。3.4 构建系统colcon、catkin_make 与纯 CMakeLivox ROS Driver2 支持三种构建方式各有用武之地。ROS2 标准方式colcon推荐大多数用 ROS2 的人采用方便后续 launch 和管理多个包。ROS1 标准方式catkin_make如果你还在 ROS1 Noetic 上用这个。纯 CMake 方式不依赖 ROS 环境直接把驱动编译成一个可执行节点。这种方式适合在嵌入式板子或者没有完整 ROS 环境的机器上提前验证代码但部署和参数配置会麻烦一些。单纯从“跑通”的角度讲我建议跟着官方 README 走 ROS2 colcon 的路线这也是社区里反馈最稳定、资料最全的路径。4. 三条实际跑通的编译路线记录4.1 路线AROS2 标准工作空间方式推荐先把最推荐的方案写完整。以下命令默认你当前用户是普通用户不要用 root 跑 colcon会有权限问题。# 1. 准备 Livox-SDK2已编译并 make install 过的前提下 export LIVOX_SDK2$HOME/Livox-SDK2 # 2. 准备 ROS2 环境 source /opt/ros/humble/setup.bash # 3. 定义编译入口变量 export ROS_VERSION2 export ROS_PACKAGE_PATH$PWD:$ROS_PACKAGE_PATH # 4. 创建并编译工作空间 mkdir -p ~/ros2_ws/src cp -r ~/livox_ros_driver2 ~/ros2_ws/src/ cd ~/ros2_ws colcon build --symlink-install--symlink-install这个参数强烈建议加上。它让编译结果里的 Python 脚本和 launch 文件以软链接方式存在后续你改配置和 launch 文件时不需要重新编译就能生效对调试非常友好。编译完成后source 一下工作空间source ~/ros2_ws/install/setup.bash4.2 路线B不建工作空间直接 CMake 编译如果你只想快速验证一下驱动能否编译通过或者你的项目本身就是独立 CMake 工程不想为了一个驱动单独建整个工作空间可以直接在驱动目录里编译cd ~/livox_ros_driver2 export LIVOX_SDK2$HOME/Livox-SDK2 export ROS_VERSION2 mkdir build cd build cmake .. make -j$(nproc)这种方式不会把驱动装成 ROS 包编译出来的可执行文件和库都留在 build 目录里。优点是快缺点是不方便启动 launch 文件也无法被其他 ROS 包依赖只适合临时验证。4.3 路线CROS1 下的 catkin_make还在 ROS1 Noetic 上的同学可以按这个来source /opt/ros/noetic/setup.bash export ROS_VERSION1 mkdir -p ~/catkin_ws/src cp -r ~/livox_ros_driver2 ~/catkin_ws/src/ cd ~/catkin_ws catkin_make source devel/setup.bash这里有一个很关键的细节ROS1 环境下ROS_VERSION环境变量默认可能已经由 ROS1 的 setup.bash 设置为 1但我依然建议显式 export 一遍。因为如果你的 shell 里之前 source 过 ROS2 的环境ROS_VERSION可能会残留为 2导致驱动在 ROS1 里走了 ROS2 的编译逻辑报错根本没法看。4.4 编译速度与性能调优编译这个驱动的时间不会太长普通四核 CPU 基本两三分钟就完事。如果你的机器配置比较差建议make -j$(nproc)里的nproc根据实际 CPU 数来避免内存不足导致 OOM。另外ROS2 的colcon build也可以限制并行度colcon build --symlink-install --parallel-workers 25. 编译报错排查全链路从链接错误到运行时异常5.1 场景一livox_sdk.h 找不到这是最经典的报错信息一般是fatal error: livox_sdk.h: No such file or directory看到这句话不用怀疑就是 Livox-SDK2 头文件路径没有暴露给编译器。排查链路如下检查$HOME/Livox-SDK2源码目录里是不是真的有头文件比如sdk_core/include/livox_sdk.h。如果源码目录不存在那就先回去把 SDK2 clone 下来。检查LIVOX_SDK2环境变量是不是指向源码目录而不是安装目录。注意驱动 CMake 脚本找的是 SDK2 源码里的 include 路径不是/usr/local/include。重新执行cmake ..让新变量生效仅仅make不会触发重配置。5.2 场景二ament_cmake 相关错误报错通常长这样Could not find a package configuration file provided by ament_cmake这句话翻译过来就是“找不到 ROS2 的构建系统组件”。原因几乎只有一个编译前没有 source ROS2 环境。排查步骤echo $ROS_DISTRO如果没输出说明 ROS2 环境没加载。执行source /opt/ros/humble/setup.bash然后再编译。这种问题常见于你开了新终端但又没有把 source 步骤写进~/.bashrc。5.3 场景三CMake 版本过低Ubuntu 20.04 自带的 CMake 是 3.16.3而 Livox 驱动可能有依赖要求更高版本。如果你遇到类似CMake 3.22 or higher is required. You are running version 3.16.3就得升级 CMake。我不建议用 apt 直接升级因为系统源里的版本通常跟不上推荐用 pip 安装最新版pip install cmake --upgrade但要注意安装完之后要确认当前 shell 用的是哪个 cmakewhich cmake cmake --version因为 pip 装的位置可能在~/.local/bin与系统/usr/bin/cmake并存PATH 顺序决定谁生效。5.4 场景四编译成功但启动时报找不到 so 文件这种最恶心编译都过了运行时给你来一击error while loading shared libraries: liblivox_sdk2.so: cannot open shared object file原因很简单动态库搜索路径里没有/usr/local/lib。如果你之前sudo make install装好了 SDK2执行一句sudo ldconfigldconfig 会刷新系统动态库缓存。要是没解决再手动指定export LD_LIBRARY_PATH/usr/local/lib:$LD_LIBRARY_PATH然后重新启动节点。如果你用的是自定义安装路径LD_LIBRARY_PATH就必须写你那个路径了。5.5 场景五改了环境变量却仿佛没生效这个坑来自编译系统缓存。你已经设置好了LIVOX_SDK2和ROS_VERSION但重新编译还是在报同样的错大概率是 build 目录里的 CMakeCache 残留了旧配置。处理方法很粗暴rm -rf build install log然后从设置环境变量开始重新走一遍。ROS2 工作空间里同理把build/install/log三个目录删干净再colcon build。很多人不敢删其实这三个目录都是生成物删了没有任何风险。6. 部署后连接雷达与点云显示的坑6.1 修改 config 文件IP、广播码与点云格式编译部署完成后真正的重头戏是让驱动连上你的雷达。驱动启动时会读取 config 目录下的 JSON 配置文件比如 Mid-360 对应的是config_mid360.json。你需要关注几个关键字段lidar_configs一个数组每个元素对应一台雷达。里面可以配多台雷达的参数比如是否启用连接、广播码、本机端口等。broadcast_code雷达的广播码一般在雷达机身标签上或二维码里能找到。留空通常表示接受任意广播码但正式使用不建议留空否则在多雷达环境下容易连到不期望的设备。enable_connect是否主动连接雷达。一般设为 true。xfer_format点云数据格式。0 是 Livox 自定义点云格式包含更多雷达原始信息1 是标准 PointCloud2 格式适合直接在 RViz 里显示。实际以你下载的仓库 README 中说明为准。修改配置时注意JSON 文件不要留注释严格按 JSON 语法来。6.2 启动驱动并解决“连接中”问题启动指令很简洁以官方提供的 launch 文件为例ros2 launch livox_ros_driver2 msg_Mid360.launch.py如果一切正常终端里会打印雷达连接状态和点云发布信息。如果一直显示初始化中或者连接超时按以下顺序排查检查主机网卡 IP 是否和雷达在同一个网段用ip addr查看。用ping探测雷达 IP 是否通则的。如果 ping 不通多半是网线、供电或者雷达本身不在线。检查防火墙是否拦截 UDP 广播。我遇到过一次 Ubuntu 上的 UFW 默认策略导致驱动发现不了雷达关掉后秒连。6.3 RViz 里看不到点云驱动跑起来后话题列表里肯定有相关话题比如/livox/lidar或/livox/points。RViz 里看不到点云绝大多数情况不是数据没发布而是 Fixed Frame 设置不对。打开 RViz 的 Global Options把 Fixed Frame 改成 config 文件里msg_frame_id对应的值比如livox_frame。然后 Add 一个 PointCloud2 显示器选择你要看的那个话题。如果这一步都做了还是空白看看 PointCloud2 的 Topic 里是不是选错了名字以及话题是否有数据进来ros2 topic hz /livox/lidar有频率输出说明数据在发纯显示问题没有频率说明驱动没真正把数据发出来要继续查驱动日志。6.4 多雷达场景的注意点如果你要同时接多台 Livox 雷达第一件事就是给每台雷达配置独立的broadcast_code和msg_frame_id。雷达默认 IP 可能一样但多台同时接同一个交换机时驱动的发现机制会通过广播码区分设备。如果你都留空有可能出现 A 雷达的数据出现在 B 雷达的话题上这种怪问题不好排查所以建议一开始就配清楚。6.5 时间同步与点云时间戳Mid-360 这类雷达支持通过 GPS/GPRMC 报文做时间同步。如果你的系统没有接 GPS雷达会降级到用自己的时钟点云时间戳可能和主机时间对不上。对于纯建图和定位应用这个偏差在短时间里影响不大但如果做多传感器融合建议还是给雷达接上时间同步信号否则后面标定和对齐时会有很多难以解释的误差。另外如果你看到点云里偶尔有“飞点”或者噪点不一定是雷达坏了。Livox 的非重复扫描特性在快速运动时会出现一些拖影这是物理特性不是配置问题。检查一下 frame_id 和 TF 树是否完整比反复调参数更能解决问题。我个人实测下来最清爽的管理方式是把 Livox-SDK2 源码和 livox_ros_driver2 源码放在同一个目录下SDK2 直接按默认路径 install驱动这边每次开新终端都统一设置一次LIVOX_SDK2、ROS_VERSION、ROS_PACKAGE_PATH三个变量。虽然看起来有点繁琐但等你同时管理多台雷达、多个 ROS2 版本的时候会发现显式设置变量带来的确定性比依赖.bashrc里一堆混乱的 export 要可靠得多。这套流程跑通之后后面做 Livox 雷达的标定、融合、建图都会顺很多。