CARLA源码编译安装完全指南：环境配置与避坑实操

1. 为什么CARLA安装这么折腾，以及我决定怎么装

前两周我在搞自动驾驶仿真的课题，说到仿真器，CARLA是绕不开的一个东西。作为一款开源的自动驾驶仿真平台，它对传感器模型、逼真环境和场景编辑的支持确实香，但安装过程是真的蹂躏人。CARLA官方文档写得挺全，可实际动手装的时候，版本对不上、依赖缺失、编译到一半内存爆炸各种问题全来了，就差没把我心态搞崩。

我这次记录的是在本地机器上从零安装CARLA的完整过程，主要是基础版本、编译安装和首次运行。为什么强调“基础版本”？因为CARLA分两种拿法，直接下载Release版压缩包，或者从源码自己编译。压缩包省事但你要迁就它给的配置，源码编译灵活但你得有耐心。我这次选择的就是源码编译，原因很简单，我想先把顶层做一遍，后续要改传感器或加自己的车辆模型会方便很多。但源码编译对机器要求非常具体，如果你也有打算入坑，请先记住三个关键词：显卡驱动、内存、Python。

这一篇更适合那些已经了解CARLA是什么、但不熟悉安装流程的开发者。如果你是零基础，想先跑个demo图一乐，我建议你直接下Release版，不要学我先编译，除非你做好折腾一周的心理准备。咱们先聊点硬核的。

2. 安装前的版本选择与环境评估

2.1 版本不匹配才是一切的根源

CARLA的坑几乎都从版本匹配这个事开始。你需要同时看四个东西：CARLA版本、虚幻引擎（Unreal Engine）版本、Python版本和操作系统版本。这四者一旦不对齐，后面每一步都像踩在裂缝上。

CARLA官方目前主要支持Ubuntu系统，而且不是所有Ubuntu版本都支持。比如CARLA 0.9.15之后的版本对Ubuntu 22.04的支持才比较完善，之前的老版本基本只建议用18.04/20.04。我用的是Ubuntu 20.04，这个版本在社区里的资料最多，出了问题也好搜。

再升级版本这一步就是Python。CARLA的API用Python实现，而它官方要求的Python版本是3.8或3.9左右，不同发布版还有严格限制。如果你机器上默认Python是3.10或3.11，建议直接用conda或venv单独建一个环境，别动系统级Python，不然你可能会把系统依赖搞挂。

2.2 硬件的底线在哪

CARLA是基于虚幻引擎开发的，所以对硬件要求不是普通代码项目那种几百MB级别的。我这次配置是16GB内存、六核CPU、一张8GB显存的显卡，另外预留了60GB磁盘空间给CARLA和引擎。

实际体验下来，16GB内存跑编译是非常吃紧的，我建议至少24GB，特别是编译到虚幻引擎那一步时，当中途几个模块并行作业，内存会瞬间冲到15GB以上，接近16GB直接卡死。当时我差点以为电脑挂了，后来我加了20GB的Swap空间才勉强救回来。所以如果你内存只有8GB，建议直接放弃源码编译，老老实实下Release包。

磁盘空间也别抠，CARLA本体、虚幻引擎缓存、编译中间文件加起来能吃掉40GB左右，不要把每个盘都塞得全是死活，到时候报“No space left on device”就晚了。

3. 开始动手：基础依赖的安装与踩坑

3.1 先确认显卡驱动和CUDA

为什么把驱动放第一个，因为CARLA在渲染的时候需要比较老练的GPU调用。没有驱动你连第一个启动命令都过不去。我建议先别急着装CUDA，Ubuntu 20.04下你用系统的“附加驱动”界面装个NVIDIA驱动就行，找到“软件与更新”，然后选驱动版本，推荐安装官方marked as recommended的那个，不用自己手动去NVIDIA官网下runfile。

确认驱动装好的命令很简单：

nvidia-smi

如果看到显卡信息列表，驱动这部分就算通过。这里有个容易被骗的点：nvidia-smi显示的CUDA Version并不是你实际安装的CUDA版本，它只是驱动所支持的最高版本。按CARLA的编译需求，你只要驱动支持CUDA 11.x以上就能跑，不需要单独装完整CUDA Toolkit。我一开始还去装了个12.x的CUDA，装完跟Python的环境冲突，后来全部卸载才清理干净，这个坑希望大家别踩。

3.2 清理外围，别让Python版本捣乱

接下来是基础编译工具和Python依赖。这一步看着简单，但最容易出现“装一半失败”。卡住的原因很多是网络源或版本问题，尤其在一些环境里pip源慢得一言难尽。

我建议先把apt源切换到国内镜像，然后把编译工具链一次性装齐：

sudo apt update && sudo apt install -y build-essential clang-10 cmake ninja-build sudo apt install -y python3.8 python3.8-dev python3.8-distutils curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py python3.8 get-pip.py

命令里特意选了Python 3.8，这是和CARLA匹配最早的一个版本。很多朋友会顺手在系统里装了Python 3.10，然后编译或调用脚本时总是莫名报错，排查到最后发现是版本不对。为保险起见，直接用python3.8别名调用，别用默认的python3，避免被系统原有的版本覆盖掉。

3.3 一个小插曲：加载官方镜像里的包失败

在装libxml2-dev和libboost-all-dev的时候，我碰到过一次包索引损坏，后来发现是之前更新中断导致的问题。解决方法是先清理和修复half-configured的包：

sudo dpkg --configure -a sudo apt install --fix-broken

然后重新安装依赖。这种问题虽然不难，但如果不处理，后面编译时有些头文件找不到。其实很多疑难杂症不是代码问题，而是系统包本身坏掉了。

4. 源码下载与CARLA核心安装过程

4.1 GitHub大仓库怎么下才靠谱

CARLA的主仓包含多个子仓库，所以要同时拉取主代码和子模块。直接git clone很容易因为文件太多或者网络问题中断，尤其是启动了许多大文件时。我不太建议直接全量clone，可以分步走：

git clone https://github.com/carla-simulator/carla cd carla git checkout <release-tag> git submodule update --init --recursive

推荐先把release tag切到你想要的版本，我用的0.9.15。等你确认签出成功后，再用git submodule update去把子模块拉下来。这个过程可能很久，因为有不少资源文件要通过LFS传输，网络不好时还会失败。

这里遇到最多的问题是“lfs下载失败”或“did not match any files”一类的报错。前者需要确保系统装了git-lfs：

sudo apt install git-lfs git lfs install

后者多半是tag名字写错了，可以用git tag -l先看一下有哪些可用标签。

4.2 编译前的钩子：CARLA依赖脚本

CARLA仓库里有一个叫Setup.sh的脚本，它主要用来下载预编译的依赖库和虚幻引擎补丁。官方文档会建议先运行：

./Setup.sh

或者指定你需要的版本：

./Setup.sh -v 0.9.15

这个脚本会拉取大约五六GB的东西，跑起来很像一个大型游戏的下载器。别全屏等它结束，建议放到后台运行，时不时看一下日志。这个脚本最大的问题不是本身，而是它默认从官方服务器拉资源，在一些区域慢得很。处理方法是在脚本中找到下载URL变量，临时改成镜像源，或者直接手动挂代理下载到Util目录下再运行脚本。注意这里我说的是加速下载，不涉及任何不合法工具，就是常规的科学做法。

脚本跑完后会有几个关键目录出现，比如Unreal/CarlaUnreal和Util/BuildTools，这些文件夹的完整性直接影响后续能否编译成功。我当时第一次运行脚本时半夜掉线了，第二天起来就看到缺失文件，重新跑一遍才过。

4.3 编译前的内核参数：内存与Swap的再调整

如果你内存不大，强烈建议在编译之前先加Swap。这一步很多人容易忽略，觉得“我有16GB内存够用了”，事实是CARLA编译到一半会同时启动多个编译任务，瞬间吃满内存。我在编译时就亲眼看着内存剩余从2GB一路跌到0。解决方案是在SSD上建Swap文件：

sudo fallocate -l 20G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile

注意fallocate在部分文件系统上可能出现问题，如果是LVM或者特殊格式，建议直接用dd建。这20G Swap帮我续了命，编译虽然慢但至少不会中途崩溃。如果你内存已经大于32GB，那这步可以不设。

4.4 编译过程：为什么不是一条命令跑完

CARLA的源码编译分成两个阶段，一个编译虚幻引擎，一个编译CARLA。官方脚本MakeLaunchAgent能帮你打包干很多事，但是直接用make launch这种命令时，会因为缺少前面步骤的环境而出错。

我当时是这样逐步执行：

cd carla make PythonAPI make launch

先编译PythonAPI，是为了生成CARLA客户端库，不然之后没法用脚本控制车辆和传感器。make launch则会编译服务器和模拟器主体。

编译时间取决于机器配置，我的机器大概跑了两个多小时。中间看着屏幕滚动近万行日志，那种心情用过Unix的人都能体会。如果你看到日志里有error:字样不要慌，先看报错是缺头文件还是内存原因，缺文件就补对应的包，内存原因就先关掉多余程序再重来一次。

编译完成后，在你构建目录下会生成CarlaUE4.sh。运行：

bash CarlaUE4.sh -quality-level=Low

就能看到那个经典的默认地图启动画面了。第一次成功把渲染窗口打开时，我长吁一口气，那感觉真的很爽。接着另开一个终端，运行Python示例脚本：

cd PythonAPI/examples python3.8 spawn_npc.py -n 10

如果能看到地图上出现十几辆车，这才算整个环境真正通了。

5. 我在安装过程中碰到的几个经典报错和排查方式

5.1 编译时引擎下载卡住或校验不一致

老是有人问“为什么我运行Setup脚本之后某个压缩包总是校验不过”。这里的根源多半是网络不稳定导致文件下载不完整。CARLA的脚本会做MD5校验，一旦失败就会重新下载。这种问题在公共网络或者丢包严重的环境中几乎无解。

我当时的处理方式是把下载好的压缩包备份起来，然后单独写一个脚本绕过校验这一步骤，直接用本地文件继续。原理很简单，把Setup.sh里的下载URL指向本地文件路径，或者把相应压缩包手动解压到目标目录。官方是不鼓励这么干的，但在特殊情况下这是最高效手段。前提是你的压缩包确实是从官网渠道完整下来的，否则后面编译报错更难受。

5.2 编译时报错“Unable to find Unreal Engine/UE4”

这个问题基本可以定位在引擎路径缺失，或者Setup.sh没有正确运行到引擎那一步。CARLA的引擎很特殊，它是修改过的UI版本，必须在仓库的Unreal/UnrealEngine目录下存在对应的源码，你在系统中安装的公共版UE4并不能混用。

排查方式很简单，看环境变量UE4_ROOT是否指向CARLA目录下的引擎路径。如果没有，可以手动指定：

export UE4_ROOT=$HOME/carla/Unreal/UnrealEngine export PATH=$UE4_ROOT/Engine/Build/Batches:$PATH

然后在配置文件中写入这两行，避免每次开终端都重复设置。很多网友在网上问“为什么明明装了UE4还是找不到”，其实都是因为路径没指对。

5.3 启动模拟器时黑屏或者卡在加载界面

这个问题常见于显卡驱动不匹配。如果是NVIDIA显卡，检查nvidia-smi和虚幻引擎日志中Vulkan初始化的部分。CARLA在Linux上默认使用Vulkan渲染，如果Vulkan没装好，启动时虽然界面弹出来了但就是全黑。

你需要安装Vulkan相关库：

sudo apt install libvulkan1 libvulkan-dev vulkan-tools

然后运行vulkaninfo检查是不是能看到完整的GPU信息。如果提示没有设备，一定是驱动层没挂上，重装驱动吧，别的都是浪费时间。

另一个可能是启动参数里加了-RenderOffScreen，这种模式按理可以无窗口运行，但有时候会导致分辨率参数混乱。拿到本地机器上跑可视化时，去掉这个参数再试。

5.4 Python API连不上服务器

服务器端顺利启动后，Python端报timeout或socket connect failed是很常见的。这里要先确认服务器是否真的启动了，而不是启动到一半崩溃又退出了。在启动页的终端里多留意日志，如果最后有一行类似“Server listening on port 2000”的信息，才是真的起来。

连接脚本时，默认都是绑在127.0.0.1:2000。如果是远程连接，记得在服务器启动命令中加上-carla-rpc-port=2000，并且检查防火墙是否放行TCP 2000。我当时就是忘了开防火墙，在本地跑远程节点连不上，查了半天最后才发现是ufw挡着。

5.5 内存不足导致编译中途被OOM Killer杀掉

如果你看到日志中有Killed或者进程被安全机制杀掉，十有八九是物理内存加Swap都不够用。除了前面提到的加Swap，还有一种办法是降低编译的并发任务数，不要在Make命令里加-j16，建议：

make -j4 launch

这样能明显缓解内存压力。代价是编译时间变长，但总比半途而废要好。如果你连-j4都跑不下去，那得考虑是不是Swap太小或者内存确实不够。16GB内存加-j4实测还可以，20GB Swap为辅，能撑住整个编译过程。

6. 总结成速查表：CARLA源码安装的步骤与避坑清单

为了让你快速对照，我把整个流程的核心步骤和常见成本整理在这里。

这张表是我日常排查用的，实际过程中百分之八十的问题都能落到这几类里。剩下一些奇奇怪怪的问题，多半是你改过某个路径或版本号没对齐。

7. 本次安装的真实体会与后续计划

我这次把CARLA从源码一步步编译跑起来，最大的体会是：这类大型仿真平台安装的核心不是命令本身，而是对整个环境的管控能力。你以为你在装一个软件玩玩，但当你开始处理版本、内存、子模块时，你实际是在管理一个中型系统工程的边界条件。这个能力对做自动驾驶仿真非常重要，毕竟之后你还要面对各种传感器驱动、数据采集、模型在环测试等更复杂的环节。

装好一个仿真器不仅意味着能打开地图，还意味着你的开发环境具备了可控性。以后想升级版本，我知道需要改哪些变量；想重装，也能在半天内恢复可用状态；甚至别人遇到同样问题时，你都能一眼判断出他错在哪里。这种经验不经过几次安装摔打是学不来的。

都说技术圈最怕“环境装不上，报错看不懂”，其实CARLA算好的，因为开源社区活跃，问题都能有解。只要你不慌，把错误日志从头到尾读一遍，联合搜索，多半能找到解决方案。实在不行，把报错复制到一个新文档，逐行翻译成人的语言，思路反而会明朗。

最后说个私藏小技巧：在编译CARLA时，每天第一次编译前，先运行一次sync && echo 3 | sudo tee /proc/sys/vm/drop_caches清理系统缓存。这个操作能让后续编译文件读写更稳定，但别频繁执行，不然对磁盘寿命也有影响。希望我的这些踩坑记录能让你少走一些弯路，咱们下一期记录见。