先说结论,这个问题在 Ubuntu 22.04 下的解决办法非常直接:缺什么装什么,装完重新跑一次 make PythonAPI 就行。
bash复制sudo apt update
sudo apt install -y patchelf
但如果你以为这篇文章只讲这一句 sudo apt install,那就太低估这个报错背后的坑了。我在解决完 patchelf 之后,又踩了几个更隐蔽的坑,比如 patchelf: cannot find section、ImportError: libCarla.so、编译产物文件异常等。这些报错如果不搞清楚因果链,即便你 apt 装完了,也照样会遇到。这篇文章就把我自己从第一次报错到最终跑起来 carla-simulator 的完整过程,用踩坑实录的方式写一遍。顺便把为什么会出现这个报错、为什么一个 ELF 工具会出现在 PythonAPI 的编译流程里、以及哪些环境因素会让问题变得诡异,都一并说明白,帮你少走一晚上弯路。
1. 为什么编译 PythonAPI 会用到 patchelf
1.1 Carla 0.9.16 的构建链条
Carla 0.9.16 的源码编译不是一条简单的 make install 流程。它分成了几个阶段:先是 make setup 准备依赖和引擎资产,然后是 make LibCarla 编译核心运行时,再往后是 make PythonAPI 生成可供 Python 调用的 C++ 扩展模块,最后还需要 make Package 打包成可部署的运行目录。每个阶段之间通过 .make 文件和 UETool 脚本控制,任何一个前置步骤失败,后面的目标都不会执行。
PythonAPI 的构建流程大致可以这样理解:它会先把 Carla 的 C++ 核心编译成 libCarla.so,然后把 Python 的 pyx 文件(Cython 源文件)编译成 C++ 文件,再编译成扩展模块 _carla.so。编译完成后,Python 侧引用这个扩展模块时需要定位 libCarla.so,靠的不是单纯地把两个文件放在一起,而是 ELF 里的 RPATH/RUNPATH 机制。patchelf 在这里的作用就是改写 _carla.so 内部的 RPATH 字段,把寻找动态库的路径指向构建目录下的正确位置。
换句话说,patchelf 是构建流程里的“螺丝刀”。它不对编译结果做功能上的改动,只是管理二进制的加载路径信息。如果你没有这个工具,Cython 编译完成的 _carla.so 就停留在原始状态,RPATH 指向的路径是构建机上的绝对路径,一旦移动或部署到别的目录,运行时就会报找不到 libCarla.so 之类的动态库错误。
1.2 为什么 Ubuntu 22.04 默认没有 patchelf
Ubuntu 的基础安装包对 patchelf 的态度是“有但不默认装”。在 Ubuntu 22.04 的官方仓库里,patchelf 是存在的,只是不会出现在标准的 build-essential 里。很多依赖 build-essential 的编译项目不会显式声明需要 patchelf,于是用户按文档装完依赖,以为万事大吉,实际在编译的最后阶段才会暴露缺失。
这个“最后阶段才暴露”真的很伤时间。因为 Carla 的完整编译时间很长,CPU 性能一般的情况下,光编译核心和 PythonAPI 可能就要一两个小时。你在最开始看不到任何问题,一路跑到底,最后一步报错,还得回去查文档查依赖。我在第一次遇到时差点以为是源码包损坏,后来用 which patchelf 一查,才发现压根没装。
另外提一句,这个问题在 Windows 上几乎不会遇到,因为 Windows 下 Carla 的构建脚本会直接生成带对应 DLL 搜索路径的 .pyd 文件,不需要 patchelf。所以很多网上搜到的解决方案都默认你用的是 Windows 或者旧版 Carla,在 Ubuntu 22.04 上就完全对不上号。遇到报错先检查基础工具链,不要急着改源码,是我这次踩坑最重要的教训。
1.3 libCarla.so 与 _carla.so 的 RPATH 关系
这里稍微展开讲一下 RPATH 机制,理解了它你就知道为什么 patchelf 不可替代。
在 Linux 下,可执行文件或动态库在被加载时,动态链接器会按照一定顺序搜索依赖的共享库。搜索路径的来源包括 LD_LIBRARY_PATH、系统缓存 /etc/ld.so.cache、以及写在 ELF 文件头里的 RPATH/RUNPATH 字段。Carla 构建出的 _carla.so 本身不包含完整的 Carla 运行时逻辑,真正的逻辑在 libCarla.so 里,所以 _carla.so 的 ELF 头里必须写明“到哪里找 libCarla.so”。
Carla 的构建脚本写死了这个路径,但实际路径在生成扩展模块之后可能变化。比如我常用的构建位置是 /home/user/carla,如果直接把编译产物打包拷贝到部署目录 /opt/carla,原始 RPATH 就失效了。patchelf --set-rpath 可以强制把 RPATH 改成 $ORIGIN 或相对路径,也就是“和当前动态库同目录”,这样无论拷到哪里,都能正确找到同目录下的 libCarla.so。
所以在编译最后阶段调用 patchelf 是 Carla 工作流里绕不开的一环。缺了这个工具,你看到的可能不是编译失败,而是运行时报错。如果你自己写动态库扩展,也建议了解一下 patchelf,很多疑难杂症都是 RPATH 惹的祸。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 完整操作流程:从零到跑通 PythonAPI
2.1 环境准备与依赖清单
先把我的环境列出来,方便对照。我的宿主机是 Windows,虚拟机是 VMware Workstation 17 Pro,虚拟机的系统是 Ubuntu 22.04.4 LTS,内存 16 GB,CPU 8 核,磁盘 80 GB。系统刚装好时是英文环境,我手动把键盘和语言调成了中文(其实对编译没有影响,纯粹个人习惯)。
在安装 Carla 之前,先把系统更新和基础工具装好。我建议按下面这
