1. 为什么我最终还是选择了源码编译这条路Autoware.universe 在 Ubuntu 22.04 上的安装方式官方其实给了好几条路有 Docker 镜像、有 apt 二进制包、也有源码编译。我一开始也是图省事直接拉 Docker 镜像跑 demo确实十分钟就能看到 RViz 里那台虚拟车动起来。但真到要改感知模块、要接自己的激光雷达、要调规划参数的时候Docker 那层封装反而成了累赘——你改一行代码要重新 build 镜像调试器挂不进去日志也隔了一层。所以折腾了两天之后我还是老老实实回到源码编译这条路。这篇东西就是把我从零开始在一台干净的 Ubuntu 22.04 上编译 Autoware.universe对应 ROS 2 Humble 版本的完整过程记录下来包括中间踩的坑、报的错、以及最后怎么绕过去的。目标读者是那些已经装过 ROS 2、对 colcon 和 CMake 有点概念但第一次碰 Autoware 这种大型工作空间的人。如果你连 ROS 2 都没装过建议先把 Humble 装好再来看这篇不然会有点吃力。先说清楚一个前提Autoware.universe 是个非常庞大的仓库光依赖的 ROS 包就有几百个编译一次在普通笔记本上跑一两个小时是常态。所以心态要放平别指望一次成功报错是必然的关键是知道每个错大概是什么原因。提示本文所有操作基于 Ubuntu 22.04 LTS ROS 2 Humble硬件是一台 16GB 内存、8 核 CPU 的机器。内存小于 8GB 的话编译后期链接阶段极容易 OOM建议提前加 swap。2. 编译前的环境盘点与依赖梳理2.1 系统版本和 ROS 2 版本的对应关系Autoware.universe 的版本和 ROS 2 发行版是强绑定的。Humble 对应的是 Ubuntu 22.04Foxy 对应的是 Ubuntu 20.04。这两个差别不只是版本号底层依赖的库版本、Python 版本Humble 是 3.10Foxy 是 3.8、甚至 colcon 的行为都有区别。所以如果你在 22.04 上硬装 Foxy 版的 Autoware基本是自找麻烦。反过来网上很多教程是 Foxy 时代的命令直接抄到 Humble 上会报一堆找不到包的错误这点要特别注意。我建议动手前先确认三件事lsb_release -a确认是 22.04echo $ROS_DISTRO确认是 humblepython3 --version确认是 3.10.x。这三个对不上后面全是白费功夫。2.2 那些官方文档没强调但必须装的依赖官方文档给的依赖安装命令大概是这样的sudo apt update sudo apt install -y \ git cmake python3-pip \ ros-humble-ros-base \ ros-dev-tools但实测下来光这些是不够的。Autoware 编译过程中会用到一堆几何、点云、可视化相关的库缺一个就卡在某个包的 CMake 配置阶段。我整理了一份实际编译时补装的清单sudo apt install -y \ ros-humble-pcl-ros \ ros-humble-pcl-conversions \ ros-humble-eigen3-cmake-module \ ros-humble-cv-bridge \ ros-humble-image-transport \ ros-humble-tf2-eigen \ ros-humble-diagnostic-updater \ libboost-all-dev \ libeigen3-dev \ libpcl-dev \ libyaml-cpp-dev \ libgeographiclib-dev \ qtbase5-dev \ libqt5opengl5-dev这里面libgeographiclib-dev和qtbase5-dev是最容易被漏掉的。前者是地理坐标转换用的Autoware 的定位模块依赖它后者是 RViz 插件编译需要的缺了会在编译autoware_rviz_plugins时报 Qt 头文件找不到。2.3 工作空间的目录规划Autoware 官方推荐用autoware_ws作为工作空间名但目录结构其实有讲究。我见过有人直接把整个 universe 仓库 clone 到src/下结果 colcon build 的时候因为嵌套太深、路径太长某些包的编译脚本会出问题。比较稳妥的做法是mkdir -p ~/autoware_ws/src cd ~/autoware_ws/src git clone https://github.com/autowarefoundation/autoware.universe.gitclone 完之后src/下应该只有一个autoware.universe目录。如果你还需要autoware_launch或者autoware_msgs这些配套仓库也一并 clone 到src/下保持平级。注意不要用--depth 1浅克隆。Autoware 的构建脚本里有些地方会读 git 历史来生成版本信息浅克隆会导致编译时报fatal: not a git repository或者版本号为空。3. 依赖安装的深水区rosdep 的正确用法3.1 rosdep 初始化为什么总是失败rosdep是 ROS 生态里管理系统依赖的工具Autoware 的依赖清单非常长靠手动装是不现实的。标准流程是sudo rosdep init rosdep update但sudo rosdep init这一步在国内网络环境下经常卡住或者直接报错提示无法下载20-default.list。这个文件其实就是个源列表本质上是去几个固定的 URL 拉 yaml 文件。如果这一步失败可以手动创建目录和文件sudo mkdir -p /etc/ros/rosdep/sources.list.d sudo tee /etc/ros/rosdep/sources.list.d/20-default.list EOF yaml https://raw.githubusercontent.com/ros/rosdistro/master/rosdep/osx-homebrew.yaml osx yaml https://raw.githubusercontent.com/ros/rosdistro/master/rosdep/base.yaml yaml https://raw.githubusercontent.com/ros/rosdistro/master/rosdep/python.yaml yaml https://raw.githubusercontent.com/ros/rosdistro/master/rosdep/ruby.yaml gbpdistro https://raw.githubusercontent.com/ros/rosdistro/master/releases/fuerte.yaml fuerte EOF然后rosdep update如果还是慢可以多试几次或者换个时间段。这一步没有特别好的绕过办法因为 rosdep 的数据库确实需要联网更新。3.2 rosdep install 时那些找不到的包初始化完成后在工作空间根目录执行rosdep install -y --from-paths src --ignore-src --rosdistro humble这条命令会扫描src/下所有package.xml把缺的依赖列出来并安装。但实际跑的时候经常会遇到某几个包Cannot locate rosdep definition。这种情况通常有两类原因一是这个包名在 rosdep 数据库里确实没有需要手动装二是包名拼写和数据库里的 key 不一致。我遇到过的几个典型报错包名实际情况解决办法geographic-msgs数据库里叫ros-humble-geographic-msgs手动 apt 安装grid-map需要从源码编译clone grid_map 仓库到 srcmorai-msgs第三方包非必需在 package.xml 里注释掉autoware-cmake同仓库内包rosdep 误判加--ignore-src已可跳过遇到这类问题不要慌先看报错的具体包名然后apt search一下有没有对应的ros-humble-xxx有就手动装没有就考虑是不是可以跳过。3.3 一个容易被忽略的坑Python 依赖Autoware 里有不少 Python 节点依赖numpy、scipy、transforms3d这些。系统自带的 pip 装的时候可能会和 apt 装的版本冲突。我的建议是统一用 apt 装 ROS 封装好的版本sudo apt install -y \ python3-numpy \ python3-scipy \ python3-transforms3d \ python3-pytest不要用pip install去装这些否则 colcon build 的时候 Python 环境混乱会出现ModuleNotFoundError但明明 pip list 里有的诡异情况。4. 正式编译colcon build 的参数怎么调4.1 第一次编译千万别直接 colcon build很多人 clone 完依赖装完直接一个colcon build就上了然后跑到一半 OOM 或者报一堆编译错误根本不知道从哪看起。正确的做法是分阶段、带参数地编译。首先Autoware 官方提供了一个setup.bash或者类似的脚本但更通用的是直接用 colcon 的参数。我推荐的第一次编译命令cd ~/autoware_ws colcon build \ --symlink-install \ --cmake-args -DCMAKE_BUILD_TYPERelease \ --parallel-workers 4 \ --event-handlers console_direct逐个解释这些参数--symlink-installPython 包和 launch 文件用软链接而不是拷贝改代码不用重新 build调试神器。-DCMAKE_BUILD_TYPERelease默认是 Debug编译出来的二进制巨大且慢Release 能省不少时间和空间。--parallel-workers 4并行编译的包数量。8 核机器建议 416 核可以 6-8。设太高内存扛不住。--event-handlers console_direct把每个包的编译输出直接打到终端方便定位是哪个包报错。4.2 内存不够时的 swap 配置Autoware 里有些包比如autoware_planning相关编译时单个进程就能吃掉 4-5GB 内存。16GB 机器在并行 4 个包的时候很容易触顶。加 swap 是最直接的缓解办法sudo fallocate -l 16G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile然后把它写进/etc/fstab让它开机自动挂载echo /swapfile none swap sw 0 0 | sudo tee -a /etc/fstabswap 虽然慢但至少不会让编译进程被 OOM killer 干掉。我实测加 16G swap 之后16GB 内存的机器可以稳定跑完整个编译。4.3 编译过程中的阶段性检查整个编译大概会持续 1-2 小时中间不要干等着。可以另开一个终端用htop看资源占用用watch -n 5 ls install/ | wc -l看已经装好的包数量。如果发现某个包卡了很久超过 10 分钟没输出大概率是卡在某个依赖下载或者 CMake 配置上可以 CtrlC 中断单独编译那个包看详细报错colcon build --packages-select 包名 --cmake-args -DCMAKE_BUILD_TYPERelease5. 那些年我踩过的编译错误与修复实录5.1 Eigen 版本冲突导致的编译失败报错长这样error: Eigen::Index has not been declared或者fatal error: Eigen/Core: No such file or directory这个问题的根源是系统里装了多个 Eigen 版本或者 Eigen 的头文件路径没被正确 include。Ubuntu 22.04 自带的 Eigen 是 3.4.0Autoware 大部分包是兼容的但个别包会硬编码/usr/include/eigen3路径。解决办法是确认libeigen3-dev装了然后在 CMake 里显式指定colcon build --cmake-args -DEigen3_DIR/usr/lib/cmake/eigen3如果还是不行检查/usr/include/eigen3/Eigen/Core是否存在。不存在就重装libeigen3-dev。5.2 PCL 相关包的链接错误报错通常是undefined reference to pcl::PCLBase...::...这是链接阶段找不到 PCL 库。原因多半是libpcl-dev版本和 ROS 自带的pcl-ros不匹配。Ubuntu 22.04 的libpcl-dev是 1.12而 Humble 的pcl-ros也是基于 1.12 编译的理论上兼容。但如果之前装过其他版本的 PCL就会冲突。排查方法dpkg -l | grep pcl如果看到多个版本的libpcl用apt remove把非 1.12 的卸掉。然后确认pcl-ros装的是 Humble 版本apt list --installed | grep pcl-ros5.3 Qt 插件编译时的 moc 错误报错Error: moc failed或者fatal error: QWidget: No such file or directory这是 RViz 插件编译时的经典问题。Autoware 的autoware_rviz_plugins包依赖 Qt5需要qtbase5-dev和libqt5opengl5-dev。如果这两个装了还报错检查CMAKE_PREFIX_PATH里有没有 Qt 的路径echo $CMAKE_PREFIX_PATH正常应该包含/usr/lib/x86_64-linux-gnu/cmake/Qt5。没有的话在编译时手动加上colcon build --cmake-args -DCMAKE_PREFIX_PATH/usr/lib/x86_64-linux-gnu/cmake/Qt55.4 Python 包的 setuptools 版本问题报错error: option --single-version-externally-managed not recognized这是setuptools版本太老或者太新导致的。Humble 的 Python 包构建依赖setuptools的特定行为。解决办法是装一个中间版本pip3 install setuptools58.2.0注意要用pip3而不是pip确保装到 Python 3.10 的环境里。装完重新编译报错的包即可。5.5 常见错误速查表错误关键词大概率原因快速修复Eigen::Index has not been declaredEigen 路径问题指定Eigen3_DIRundefined reference to pcl::PCL 版本冲突卸载多余 PCL 版本moc failedQt 开发包缺失装qtbase5-devsingle-version-externally-managedsetuptools 版本降级到 58.2.0Cannot locate rosdep definitionrosdep 数据库缺条目手动 apt 装或跳过Killed内存不足加 swap 或降并行数not a git repository浅克隆重新完整 clone6. 编译完成后的环境配置与验证6.1 source 的顺序不能乱编译成功后install/目录下会有setup.bash。source 的时候要注意顺序先 source ROS 2 的再 source 工作空间的。source /opt/ros/humble/setup.bash source ~/autoware_ws/install/setup.bash如果顺序反了工作空间里的包会被 ROS 2 自带的同名包覆盖导致运行时找不到某些节点。建议把这两行写进~/.bashrc但要注意写的时候用绝对路径别用相对路径。6.2 验证编译是否真的成功光看 colcon build 最后输出Summary: X packages finished还不够要实际跑一下。最简单的验证是启动一个 launch 文件ros2 launch autoware_launch planning_simulator.launch.xml如果 RViz 能起来并且能看到地图和车辆模型说明核心包都编译成功了。如果报package not found说明 source 没生效或者某个包没编译进去。另一个验证方法是列一下所有已安装的包ros2 pkg list | grep autoware | wc -l正常应该有 200 个以上。如果只有几十个说明编译中途失败了很多包需要回头看编译日志。6.3 运行时的动态库加载问题有时候编译成功了但运行时报error while loading shared libraries: libxxx.so: cannot open shared object file这是因为某些包编译出来的动态库不在LD_LIBRARY_PATH里。解决办法是在 sourcesetup.bash之后手动确认一下echo $LD_LIBRARY_PATH | tr : \n | grep autoware应该能看到install/下各个包的lib目录。如果没有说明setup.bash没正确设置可以手动加export LD_LIBRARY_PATH$LD_LIBRARY_PATH:~/autoware_ws/install/autoware_core/lib7. 一些让编译更顺手的经验之谈7.1 用 ccache 加速二次编译Autoware 这种大工程改一个包重新编译如果不用 ccache每次都要重头来。ccache 会缓存编译结果二次编译能快 50% 以上。装法sudo apt install ccache然后在 colcon build 时指定colcon build --cmake-args -DCMAKE_C_COMPILER_LAUNCHERccache -DCMAKE_CXX_COMPILER_LAUNCHERccache第一次编译会慢一点要写缓存但之后改代码重编就非常快。7.2 选择性编译别每次都全量Autoware 有几百个包但你实际开发的可能就那几个。colcon 支持--packages-up-to和--packages-select# 只编译某个包及其依赖 colcon build --packages-up-to autoware_planning # 只编译某个包不编译依赖 colcon build --packages-select autoware_planning日常开发用--packages-up-to就够了能省大量时间。7.3 日志怎么看才高效colcon 的日志默认在log/latest_build/下每个包一个目录。报错的时候不要从头翻直接grep -r error log/latest_build/ | head -50或者看某个包的stderr.logcat log/latest_build/包名/stderr.log这样能快速定位到具体是哪个文件哪一行报的错。7.4 关于 Humble 和 Foxy 的差异再补充几句如果你之前玩过 Foxy 版的 Autoware迁移到 Humble 时要注意几个变化一是launch文件的语法有调整param标签的行为变了二是tf2的 API 有细微改动某些旧代码会编译不过三是 Python 版本从 3.8 升到 3.10一些依赖旧版本特性的脚本会挂。这些在编译阶段可能不报错但运行时会出问题所以迁移时最好把相关模块的代码过一遍。8. 最后分享几个排查思路编译 Autoware 这件事说到底是个耐心活。我的经验是遇到报错先别急着搜先看报错信息里的关键词判断是依赖问题、版本问题还是代码问题。依赖问题用 apt 解决版本问题用指定路径或降级解决代码问题才需要去翻 issue。另外编译环境尽量保持干净。我见过有人在同一个系统上装了 Foxy 和 Humble 两套 ROS结果编译 Autoware 时 CMake 找到的是 Foxy 的库报了一堆莫名其妙的错。如果条件允许用虚拟机或者 Docker 隔离一个专门的环境会省很多事。还有一个细节编译前把~/.colcon/defaults.yaml里的默认参数配好比如并行数、CMake 参数这样每次 build 不用敲一长串。这个文件 colcon 会自动读配置一次终身受益。build: cmake-args: - -DCMAKE_BUILD_TYPERelease parallel-workers: 4 symlink-install: true把这些写进去之后直接colcon build就会带上这些参数省心不少。