Ubuntu 20.04源码编译Carla 0.9.4：从环境配置到Python API适配全攻略

1. 项目概述与核心挑战如果你正在为自动驾驶、机器人仿真或者游戏开发寻找一个功能强大的开源模拟器那么Carla绝对是一个绕不开的名字。作为一个基于Unreal Engine构建的、专注于自动驾驶研究的开源模拟器Carla提供了高度逼真的城市环境、丰富的传感器模型如摄像头、激光雷达、GPS以及灵活的Python/C API让研究人员和开发者能够在虚拟世界中安全、高效地测试和验证自己的算法。然而直接从官方提供的预编译包安装Carla虽然简单但往往无法满足深度定制、二次开发或者特定版本兼容性的需求。这时从源码编译就成了唯一的选择。我最近在Ubuntu 20.04 LTS系统上成功从源码编译了Carla 0.9.4版本并适配了Python 3.8环境。整个过程堪称一场“硬仗”官方文档虽然详尽但更像一份“理想情况”下的说明书在实际操作中你会遇到各种依赖冲突、网络超时、编译错误尤其是在国内网络环境下下载UE4源码和Carla资源包的速度慢到令人绝望。这篇教程就是我踩过无数坑之后为你整理的一份“保姆级”实战指南。我会详细拆解每一个步骤不仅告诉你“怎么做”更会解释“为什么这么做”并重点分享如何配置国内镜像源来加速下载以及解决Python 3.8适配过程中的典型问题。无论你是刚接触Carla的新手还是需要特定版本进行项目集成的开发者跟着这篇指南走都能大大降低你的编译门槛。2. 环境准备与系统配置在开始编译这座“大厦”之前我们必须确保地基足够稳固。Carla的编译对系统资源要求极高不仅仅是硬件软件环境的纯净与正确配置更是成功的关键。2.1 硬件与系统要求核查首先请对照以下清单检查你的Ubuntu 20.04系统是否满足最低要求磁盘空间这是第一个也是最重要的门槛。官方建议预留130GB空间。根据我的实测编译完成后整个工作目录包含Unreal Engine 4.26和Carla源码及资源会占用约120-140GB。我强烈建议你准备至少200GB的可用空间为编译过程中的临时文件、缓存以及未来的开发留出余地。你可以使用df -h命令查看磁盘使用情况。GPUCarla是一个图形密集型应用。虽然编译过程不强制要求独立显卡但后续运行模拟器时一块性能足够的NVIDIA GPU是流畅体验的保障。建议使用GTX 1060 6GB或更高性能的显卡。务必提前安装好NVIDIA官方驱动和CUDA工具包如果需要进行深度学习相关测试。可以使用nvidia-smi命令来验证驱动是否安装成功。CPU与内存编译Unreal Engine和Carla是极其消耗CPU和内存的过程。建议使用至少4核8线程的CPU如Intel i7或AMD Ryzen 5系列和16GB以上的内存。在编译高峰期内存占用可能超过10GB。网络整个过程中需要从GitHub、Bitbucket等外网仓库克隆大量代码和资源总计数十GB。稳定的网络连接至关重要这也是我们后面要重点使用国内镜像源的原因。2.2 基础依赖包安装Ubuntu 20.04的默认软件源版本可能较低我们首先更新源并安装编译所需的基础工具链。以下命令涵盖了Carla官方文档列出的所有依赖并额外添加了一些实用工具。sudo apt-get update sudo apt-get upgrade -y接下来安装核心的编译工具和库。注意Ubuntu 20.04默认的GCC版本是9而Carla官方推荐使用g-9所以我们直接安装即可。sudo apt-get install -y \ build-essential \ g-9 \ cmake \ ninja-build \ libvulkan1 \ python3 \ python3-dev \ python3-pip \ python3-venv \ autoconf \ wget \ curl \ rsync \ unzip \ git \ git-lfs \ libpng-dev \ libtiff5-dev \ libjpeg-dev \ pkg-config \ libssl-dev \ libboost-all-dev \ aria2 \ screen注意aria2是一个多线程下载工具在后续下载大型资源包时能显著提升速度强烈建议安装。screen工具则允许你在后台运行长时间编译任务防止因SSH断开导致编译中断。2.3 配置Git与Git LFS由于需要克隆Unreal Engine和Carla的代码仓库其中包含大量通过Git LFS管理的大文件正确配置Git至关重要。# 配置Git用户信息请替换成你自己的 git config --global user.name Your Name git config --global user.email your.emailexample.com # 启用Git LFS git lfs install实操心得在开始克隆UE4仓库前建议先测试一下Git LFS是否工作正常。可以找一个包含LFS文件的测试仓库试试。有时企业网络或代理设置会导致LFS拉取失败提前发现可以避免在编译中途卡住。3. 构建Unreal Engine 4.26 (Carla定制版)Carla并非使用标准的Unreal Engine而是其一个定制化的分支。这一步是编译过程中最耗时、也最容易出错的环节。3.1 克隆Unreal Engine仓库首先你需要有一个关联了Epic Games组织的GitHub账户。如果没有请先去Epic Games官网关联你的GitHub账号。这是克隆其私有仓库的必要条件。然后我们使用git clone命令来获取代码。这里有一个关键技巧由于仓库巨大约几十GB使用--depth 1参数只克隆最近的一次提交可以节省大量时间和磁盘空间因为历史提交对我们编译来说不是必需的。# 创建一个专门的工作目录保持系统整洁 mkdir -p ~/carla-dev cd ~/carla-dev # 克隆Carla定制版的Unreal Engine 4.26 # 注意这里的URL是Carla团队维护的fork git clone --depth 1 -b carla https://github.com/CarlaUnreal/UnrealEngine.git ~/carla-dev/UnrealEngine-4.26国内镜像加速方案直接克隆github.com/CarlaUnreal/UnrealEngine对于国内用户可能速度极慢甚至失败。虽然这个仓库是私有的无法直接通过Gitee等镜像但我们可以通过配置Git代理来加速。如果你有可用的网络代理可以这样设置# 设置HTTP/HTTPS代理请替换为你的代理地址和端口 git config --global http.proxy http://your-proxy-address:port git config --global https.proxy https://your-proxy-address:port # 克隆完成后可以取消代理设置 git config --global --unset http.proxy git config --global --unset https.proxy如果没有代理则只能依赖网络本身的稳定性或者寻找一些第三方缓存的源码包但需注意版权和版本一致性风险。3.2 编译Unreal Engine进入目录开始编译。这个过程非常漫长在我的至强E5-2680 v4 (14核28线程) 服务器上也花费了接近2个小时。cd ~/carla-dev/UnrealEngine-4.26 # 运行设置脚本它会下载一些必要的二进制组件 ./Setup.shSetup.sh脚本运行过程中会提示你接受EULA最终用户许可协议你需要手动输入“y”并按回车确认。接着生成项目文件并开始编译./GenerateProjectFiles.sh make重要警告绝对不要使用make -j$(nproc)来调用所有核心进行并行编译官方文档明确警告这会因为Clang的内部并行机制导致编译失败。make命令本身会进行合理的并行化我们只需耐心等待。编译成功后你可以运行以下命令来验证UE4编辑器是否能正常启动这是一个简单的功能测试cd ~/carla-dev/UnrealEngine-4.26/Engine/Binaries/Linux ./UE4Editor如果弹出了Unreal Engine的编辑器窗口恭喜你最艰难的一步已经完成。你可以关闭编辑器窗口。3.3 设置关键环境变量为了让后续的Carla编译脚本能找到我们刚刚编译好的UE4需要设置一个环境变量UE4_ROOT。# 临时设置仅对当前终端会话有效 export UE4_ROOT~/carla-dev/UnrealEngine-4.26为了永久生效避免每次打开新终端都要重新设置最好将其添加到你的shell配置文件中。# 如果你使用的是bash echo export UE4_ROOT~/carla-dev/UnrealEngine-4.26 ~/.bashrc source ~/.bashrc # 如果你使用的是zsh echo export UE4_ROOT~/carla-dev/UnrealEngine-4.26 ~/.zshrc source ~/.zshrc验证变量是否设置成功echo $UE4_ROOT应该输出/home/你的用户名/carla-dev/UnrealEngine-4.26。4. 获取与构建Carla 0.9.4源码完成UE4的构建后我们就可以开始处理Carla本体了。4.1 克隆Carla源码仓库Carla的主仓库在GitHub上我们同样使用git clone命令来获取特定版本0.9.4的代码。cd ~/carla-dev # 克隆ue4-dev分支这是与UE4.26兼容的开发分支。0.9.4版本对应特定的提交。 git clone -b ue4-dev https://github.com/carla-simulator/carla.git cd carla # 切换到0.9.4版本对应的提交tag。你可以通过 git tag | grep 0.9.4 查看精确的tag名。 git checkout 0.9.4为了方便后续命令的编写我们也设置一个指向Carla根目录的环境变量。export CARLA_ROOT~/carla-dev/carla echo export CARLA_ROOT~/carla-dev/carla ~/.bashrc # 或 ~/.zshrc source ~/.bashrc4.2 下载CARLA资源包使用国内镜像加速这是另一个巨大的下载任务。Carla的资源包包含地图、车辆、行人模型等存储在Bitbucket上国内直连速度堪忧。官方提供了两种方式使用Update.sh脚本或git克隆。这里我强烈推荐使用Update.sh脚本并对其进行改造以使用国内镜像源。首先查看Update.sh脚本找到资源包的下载URL。通常它指向https://carla-assets.s3.amazonaws.com/或类似地址。我们可以手动寻找可用的国内镜像或者使用下载工具加速。一个更可靠的方法是先尝试直接运行脚本如果速度太慢就中断它然后手动下载。脚本下载的是一个.tar.gz压缩包。我们可以使用aria2这个多线程下载工具来加速。假设从脚本或文档中得知0.9.4版本的资源包URL是https://carla-assets.s3.amazonaws.com/Assets_0.9.4.tar.gz。使用aria2多线程下载cd ~/carla-dev/carla # 使用aria2指定16个连接数断点续传 aria2c -x 16 -s 16 -c https://carla-assets.s3.amazonaws.com/Assets_0.9.4.tar.gz手动寻找备用源有时这些资源包会被热心的社区成员同步到国内的网盘或镜像站。你可以在Carla的中文社区、论坛或相关技术博客中搜索 “Carla 0.9.4 资源包 国内镜像” 等关键词。找到后用wget或aria2c下载到~/carla-dev/carla目录下。解压资源包无论通过哪种方式下载到Assets_0.9.4.tar.gz文件都需要将其解压到正确的目录。# 创建目标目录如果不存在 mkdir -p ./Unreal/CarlaUE4/Content/Carla # 解压到指定目录 tar -xzvf Assets_0.9.4.tar.gz -C ./Unreal/CarlaUE4/Content/Carla解压后Carla目录下应该会出现Maps、Static、Vehicle等子文件夹。踩坑记录务必确保资源包解压的路径完全正确是Unreal/CarlaUE4/Content/Carla。路径错误会导致启动编辑器时地图一片空白没有任何模型。5. 编译Python API客户端与服务器现在所有原材料都已备齐可以开始编译Carla的核心组件了。5.1 Python环境配置与依赖安装Carla的Python API是其灵魂它允许你通过Python脚本控制整个仿真。首先我们需要安装Python依赖。这里有一个0.9.4版本可能遇到的巨大坑点NumPy版本冲突。Carla 0.9.4及其周边依赖特别是Boost.Python是为NumPy 1.x系列构建的。如果你的系统Python环境或虚拟环境中安装了NumPy 2.0.0或更高版本编译一定会失败。因此我们的第一步是创建一个干净的Python 3.8虚拟环境并严格控制NumPy版本。cd ~/carla-dev # 创建Python 3.8虚拟环境。确保系统已安装python3.8-venv。 python3.8 -m venv carla-venv # 激活虚拟环境 source carla-venv/bin/activate激活后你的命令行提示符前会出现(carla-venv)字样。接下来安装依赖。我们先升级pip然后从requirements.txt安装。但为了保险起见我们显式地指定NumPy版本。(carla-venv) python -m pip install --upgrade pip # 先安装一个兼容的NumPy版本 (carla-venv) python -m pip install numpy1.24 # 对于Python 3.8安装1.23.x系列通常是安全的 # 然后安装Carla的其他依赖 (carla-venv) python -m pip install --upgrade -r ${CARLA_ROOT}/PythonAPI/carla/requirements.txtrequirements.txt里可能包含numpy但由于我们已经先安装了指定版本pip会跳过或解决依赖。5.2 编译Python API在虚拟环境激活的状态下运行编译命令。这个步骤会生成一个.whl文件这就是Carla的Python客户端库。(carla-venv) cd ${CARLA_ROOT} (carla-venv) make PythonAPI这个过程会编译CarlaLib和绑定Python的模块。如果一切顺利你会在${CARLA_ROOT}/PythonAPI/carla/dist/目录下找到一个类似carla-0.9.4-cp38-cp38-linux_x86_64.whl的文件。编译成功后立即安装这个whl文件到当前虚拟环境(carla-venv) python -m pip install ${CARLA_ROOT}/PythonAPI/carla/dist/carla-*.whl你可以用python -c import carla; print(carla.__version__)来测试是否安装成功。5.3 编译并启动Carla服务器Unreal Editor这是最后一步将Carla的Unreal项目编译并启动编辑器。(carla-venv) cd ${CARLA_ROOT} (carla-venv) make launchmake launch命令会启动Unreal Engine编辑器并加载Carla项目。第一次启动会非常慢因为编辑器需要编译Shader着色器和构建网格距离场等。你会看到编辑器窗口弹出底部有编译进度条。请耐心等待直到编辑器界面完全加载并且左下角的编译提示消失。在编辑器中你可以点击顶部工具栏的“播放”按钮来启动仿真服务器。此时Carla服务器就开始在本地运行并监听默认的端口通常是2000和2001。6. 测试与验证编译完成并启动服务器后我们必须进行测试确保一切功能正常。6.1 基础功能测试保持Unreal Editor中的仿真处于运行状态即点击了Play按钮。打开一个新的终端窗口。激活虚拟环境并运行示例脚本cd ~/carla-dev source carla-venv/bin/activate cd ${CARLA_ROOT}/PythonAPI/examples # 运行一个生成行人和车辆的脚本 (carla-venv) python3 generate_traffic.py -n 20 -w 30如果一切正常你应该能在Unreal Editor的仿真窗口中看到汽车和行人在街道上移动。运行传感器示例 再开一个终端运行一个带有摄像头的示例。cd ~/carla-dev source carla-venv/bin/activate cd ${CARLA_ROOT}/PythonAPI/examples (carla-venv) python3 manual_control.py这会弹出一个PyGame窗口显示ego车辆你控制的车的摄像头画面你可以用方向键或WASD控制车辆。6.2 常见问题与排查技巧即使严格遵循步骤你也可能遇到一些问题。下表汇总了我遇到的一些典型问题及解决方案问题现象可能原因排查与解决步骤make PythonAPI失败提示Boost.Python或NumPy相关错误。1. Python虚拟环境未激活或激活不正确。2. NumPy版本不兼容2.0.0。3. Python开发头文件缺失。1. 确认终端提示符有(carla-venv)用which python检查路径。2. 在虚拟环境中执行pip show numpy确保版本低于2.0.0且高于1.17。可尝试pip install numpy1.24。3. 确保已安装python3-dev包。make launch启动后编辑器窗口一片漆黑或地图加载不出模型。1. 资源包未下载或解压路径错误。2. Shader编译未完成。3. 项目文件损坏。1. 检查${CARLA_ROOT}/Unreal/CarlaUE4/Content/Carla目录是否包含大量内容。2. 首次启动需等待Shader编译完成查看编辑器底部状态栏。3. 尝试make clean后重新make launch。运行Python脚本时报错ModuleNotFoundError: No module named carla。1.carla的.whl文件未安装。2. 在错误的Python环境非虚拟环境中运行。1. 确认已在虚拟环境中执行pip install carla-*.whl。2. 运行脚本前务必source carla-venv/bin/activate。编辑器或仿真运行时帧率FPS极低。1. 编辑器在后台运行时降低了CPU占用率。2. 系统显卡驱动或CUDA有问题。3. 场景复杂度太高。1. 在Unreal Editor中点击Edit - Editor Preferences - Performance取消勾选“Use Less CPU when in Background”。2. 确保已安装专有显卡驱动并用nvidia-smi确认GPU正在被使用。3. 在脚本中减少车辆和行人生成数量。克隆UE4或下载资源包速度极慢或失败。网络连接问题。1. 为Git配置代理如适用。2. 使用aria2c多线程下载资源包。3. 寻找社区提供的国内镜像或网盘备份。编译过程中内存不足系统卡死或报错。系统物理内存或交换空间不足。1. 增加系统的交换空间Swap。2. 尝试在编译时关闭其他内存占用大的程序。3. 如果使用虚拟机请为虚拟机分配更多内存建议16GB以上。6.3 性能优化与日常使用建议成功运行后这里有一些让你的Carla体验更顺畅的建议使用打包版本进行开发每次开发都通过make launch启动编辑器太慢。你可以使用make package命令创建一个独立的分发包。这个命令会生成一个位于Dist文件夹下的可执行包你可以直接运行./CarlaUE4.sh来启动无编辑器的专用服务器速度更快资源占用更少。在开发Python客户端时连接这个服务器即可。管理多个Carla版本通过创建不同的虚拟环境如carla-0.9.4-venv,carla-0.9.12-venv并在每个环境中安装对应版本的.whl文件可以轻松切换不同版本的Carla进行测试。备份你的工作整个编译目录~/carla-dev非常庞大但其中大部分是编译生成的二进制文件和中间文件。你可以考虑备份UnrealEngine-4.26的源码和carla的源码以及下载好的资源包。下次在新系统上部署时可以直接拷贝这些“原材料”只重新编译能节省大量下载时间。从源码编译Carla无疑是一个复杂的过程它融合了系统配置、依赖管理、大型C项目编译和Python环境配置等多方面的知识。但一旦成功你就获得了对Carla模拟器最深入的控制权可以自由地修改底层逻辑、添加自定义传感器、或者集成到更复杂的机器人系统中。希望这份结合了官方指南和实战经验的教程能帮你顺利搭建起属于自己的Carla仿真世界。如果在操作中遇到了本指南未覆盖的新问题不妨去Carla的官方论坛或相关的开发者社区搜索通常你遇到的坑早已有前辈填平了。