Ubuntu 20.04下Carla 0.9.13与UE4.26环境搭建全攻略

1. 项目概述与核心价值

如果你正在自动驾驶仿真、数字孪生或者机器人研究领域摸索，那么Carla和Unreal Engine 4（UE4）这套组合拳对你来说绝对不陌生。Carla作为一个开源的自动驾驶仿真平台，其逼真的渲染效果和灵活的传感器模拟能力，很大程度上依赖于UE4这个强大的游戏引擎作为后端。然而，将Carla 0.9.13与UE4.26在Ubuntu 20.04上成功配对，这个过程本身就像一场硬核的“系统集成”考试，充满了版本依赖、编译陷阱和环境配置的“坑”。

我最近为了复现一个多智能体协同驾驶的实验，不得不重新搭建这套环境。网上能找到的教程要么年代久远，要么步骤跳跃，照着做十有八九会卡在某个编译错误或者诡异的依赖缺失上。经过几天的折腾和无数次的虚拟机快照回滚，我终于梳理出了一条相对顺畅的安装路径。这篇指南的目的，就是把我踩过的坑、验证过的步骤以及关键的避雷点系统地分享出来，让你能绕过那些令人头疼的障碍，把宝贵的时间用在真正的算法开发和仿真测试上，而不是无休止地解决环境问题。

简单来说，这个指南适合所有需要在Linux环境下，特别是Ubuntu 20.04上，搭建Carla 0.9.13仿真环境的研究者、开发者和学生。无论你是想跑通官方示例，还是进行二次开发，一个稳定、正确的底层环境是第一步，也是最关键的一步。

2. 环境准备与前置条件核查

在动手下载任何安装包之前，花半小时彻底检查并准备好你的系统环境，能为你后续节省数小时甚至数天的排错时间。Ubuntu 20.04是一个长期支持版本，社区支持好，但针对Carla和UE4这种对系统组件有特定要求的软件，仍需精细配置。

2.1 系统与硬件要求

首先，确认你的硬件是否扛得住。UE4编辑器本身就是一个资源消耗大户，加上Carla仿真运行时，对硬件的要求不低。

• CPU: 建议至少是6核以上的现代处理器。编译UE4和Carla时，多核心能显著加速。
• 内存:绝对不要低于16GB，32GB是舒适进行开发的推荐配置。编译UE4源码时，内存消耗峰值可能超过10GB，如果内存不足，编译进程可能会被系统终止，报出一些难以理解的错误。
• 显卡: 必须是一块NVIDIA显卡，并且需要安装专有的驱动。Carla的传感器渲染（如相机、激光雷达）严重依赖GPU。集成显卡或AMD显卡（在Linux下）无法正常运行UE4编辑器或无法获得Carla的最佳性能。我的测试环境是一块RTX 3060。
• 磁盘空间: 准备至少150GB的可用空间。UE4引擎源码及其编译产物就会占用80-100GB，Carla本身也要几十GB，再加上Swap空间和后续项目文件，空间多多益善。

对于操作系统，我强烈建议在一个物理安装的Ubuntu 20.04.6 LTS上操作，而不是虚拟机（VMware/VirtualBox）。即便你给虚拟机分配了足够的CPU核心和内存，并开启了3D加速，在虚拟机内编译和运行UE4仍然会遇到无数图形驱动相关的问题，成功率极低。如果你只有Windows主机，可以考虑使用双系统，或者寻找其他变通方案（如基于Docker的Carla运行，但这仅限于使用预编译的版本，无法进行UE4编辑和自定义地图开发）。

2.2 关键系统组件安装与配置

登录你的Ubuntu 20.04系统，打开终端，我们开始进行一系列关键的安装和配置。

1. 更新系统与安装基础工具:

   sudo apt update sudo apt upgrade -y sudo apt install -y wget curl git software-properties-common apt-transport-https ca-certificates gnupg lsb-release

   这确保了你的系统是最新的，并安装了后续步骤需要的下载、版本管理等工具。

2. 安装并配置合适版本的CMake: Carla 0.9.13的编译需要CMake 3.13或更高版本，但Ubuntu 20.04默认仓库的版本是3.16.3，基本够用。为了保险起见，我们安装一个较新的版本。

   sudo apt install -y cmake cmake --version # 确认版本 >= 3.13

3. 安装Python3及Pip: Carla的Python API是其核心接口。Ubuntu 20.04默认自带Python 3.8，这正好是Carla 0.9.13推荐使用的版本。我们确保pip也已安装。

   sudo apt install -y python3 python3-pip python3-dev

   注意：不要随意升级系统默认的Python 3.8到更高版本（如3.10），这可能导致一些系统工具或后续依赖出现兼容性问题。我们使用Python虚拟环境来隔离项目依赖。

4. 安装NVIDIA显卡驱动: 这是整个流程中最容易出错的环节之一。不要使用Ubuntu“软件和更新”附加驱动里推荐的版本，也不要用sudo apt install nvidia-driver-xxx这种简单命令，因为版本可能不匹配或安装不完整。

   • 首先，添加官方PPA仓库并安装推荐驱动:

     sudo add-apt-repository ppa:graphics-drivers/ppa sudo apt update ubuntu-drivers devices # 查看推荐的驱动版本

     假设推荐的是nvidia-driver-535。
   • 安装驱动并禁用系统自带的Nouveau驱动:

     sudo apt install -y nvidia-driver-535

     安装过程中，如果提示禁用Secure Boot，请根据提示设置一个密码并在重启后输入。 安装完成后，必须重启系统。
   • 重启后验证:

     nvidia-smi

     如果这个命令能正确输出你的GPU信息、驱动版本和CUDA版本（驱动自带一个兼容的CUDA运行时库），那么驱动安装就成功了。你会看到类似“CUDA Version: 12.2”的字样，这没关系，UE4和Carla编译用的是我们后面专门安装的CUDA Toolkit。

5. 安装CUDA Toolkit 11.4: UE4.26官方兼容的CUDA版本是11.4。我们必须安装这个特定版本。

   • 前往NVIDIA CUDA Toolkit存档网站，找到CUDA Toolkit 11.4.4的Linux -> x86_64 -> Ubuntu -> 20.04 -> runfile (local)版本。用wget下载。

     wget https://developer.download.nvidia.com/compute/cuda/11.4.4/local_installers/cuda_11.4.4_470.82.01_linux.run

   • 运行安装程序，在安装选项中务必取消勾选Driver，因为我们已经安装了更新的驱动。

     sudo sh cuda_11.4.4_470.82.01_linux.run

     在弹出的文本界面中，通过回车键展开“Driver”选项，按空格键取消其选中（前面的[X]变成[ ]），然后移动到“Install”并回车。
   • 配置环境变量。编辑~/.bashrc文件：

     nano ~/.bashrc

     在文件末尾添加：

     export PATH=/usr/local/cuda-11.4/bin${PATH:+:${PATH}} export LD_LIBRARY_PATH=/usr/local/cuda-11.4/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}

     保存退出后，执行source ~/.bashrc。验证安装：nvcc --version，应显示11.4。

6. 安装其他编译依赖: UE4和Carla的编译需要一大堆开发库。

   sudo apt install -y build-essential clang-11 clang++-11 lld-11 g++-9 gcc-9 \ libxerces-c-dev libssl-dev libpng-dev libjpeg-dev libglew-dev \ libglm-dev libjsoncpp-dev libcurl4-openssl-dev libogg-dev \ libvorbis-dev libcairo2-dev libzstd-dev libbz2-dev \ libfreetype6-dev libgtk2.0-dev libgtk-3-dev libasound2-dev \ libpulse-dev libudev-dev libyaml-cpp-dev libopenal-dev \ libsndfile1-dev libboost-all-dev

   这里特别指定了clang-11和g++-9，因为UE4.26对这些编译器的版本有明确要求。

3. UE4.26 引擎源码编译详解

这是整个过程中最耗时、也最容易出错的环节。我们不会使用Epic Games Launcher安装的二进制版本，因为Carla需要链接到UE4的特定模块，必须从源码编译。

3.1 获取UE4源码

1. 注册Epic Games账户并关联GitHub：前往Epic Games官网注册账户，并在账户设置中连接你的GitHub账户。
2. 同意许可协议：访问Unreal Engine的GitHub页面，点击“Sign in”用你的Epic账户登录，然后同意开发者许可协议。
3. 克隆源码：这需要下载约30GB的数据，请确保网络稳定。

   git clone --depth 1 -b 4.26 https://github.com/EpicGames/UnrealEngine.git ~/UnrealEngine_4.26 cd ~/UnrealEngine_4.26

   使用--depth 1只克隆最新提交，节省时间和空间。

3.2 配置与编译环境准备

UE4提供了一个配置脚本，用于下载必要的二进制依赖（如.NET Core、Visual Studio编译器等Linux版本）。

./Setup.sh

这个脚本会运行相当长一段时间（取决于网速），它会检查并下载大约8GB的依赖文件。过程中需要你确认许可协议。

完成后，生成项目文件并验证配置：

./GenerateProjectFiles.sh

这个步骤会检查你的系统环境，如果前面依赖安装有遗漏，这里可能会报错。

3.3 执行编译

这是对CPU、内存和耐心的终极考验。使用make命令进行编译，并指定-j参数来利用多核CPU加速。假设你的CPU有8个逻辑核心：

make -j 8

或者，使用UE4自带的构建脚本，它内部也会调用make：

./Engine/Build/BatchFiles/Linux/Build.sh Linux Development -j 8

编译过程可能持续2到6小时。你会看到终端里飞速滚动的编译信息。在这个过程中，请重点关注以下几点：

• 内存不足：如果编译进程突然大量失败，提示“virtual memory exhausted”或“killed”，基本是内存（或Swap）用尽了。尝试减少-j后的数字（如改为-j 4），或者增加系统的Swap空间。
• 特定模块编译错误：有时会卡在某个模块，比如ShaderCompileWorker。这可能是由于临时文件问题。可以尝试先清理再单独编译：

  make ShaderCompileWorker -j 8

  如果还不行，搜索具体的错误信息，很可能是某个系统库的版本或路径问题。
• 耐心等待：只要前期依赖安装正确，编译最终应该能成功。最怕的就是在编译了90%之后报错，所以一次成功的编译弥足珍贵。

编译成功后，在~/UnrealEngine_4.26/Engine/Binaries/Linux/目录下会生成UE4Editor可执行文件。你可以运行./UE4Editor来测试编辑器是否能正常启动。第一次启动会进行着色器编译，又会等待一段时间。

4. Carla 0.9.13 源码编译与集成

有了编译好的UE4引擎，接下来就是编译Carla并将其与UE4关联起来。

4.1 获取Carla源码并更新子模块

git clone --depth 1 -b 0.9.13 https://github.com/carla-simulator/carla.git ~/carla cd ~/carla git submodule update --depth 1 --init

同样使用--depth 1加速克隆。更新子模块是必须的，它包含了RPCLib、Boost.Python等关键依赖。

4.2 设置UE4引擎路径

Carla的构建系统需要知道我们刚才编译的UE4引擎在哪里。通过环境变量来设置：

export UE4_ROOT=~/UnrealEngine_4.26

我建议把这句话也加到你的~/.bashrc里，方便后续操作。

4.3 编译Carla客户端与服务器

Carla的编译分为两部分：LibCarla（客户端库）和Unreal（服务器端，即UE4插件和资产）。

1. 编译LibCarla：

   cd ~/carla make PythonAPI -j 8

   这个命令会：

   • 编译Carla的C++核心库。
   • 生成用于Python绑定的carla-*.egg文件。生成的.egg文件会在PythonAPI/carla/dist/目录下。记下这个文件的完整名称，例如carla-0.9.13-py3.8-linux-x86_64.egg。

2. 编译Unreal引擎端的插件和资产（Carla服务器）：

   cd ~/carla make launch -j 8

   这个命令会：

   • 将Carla插件复制到UE4_ROOT中。
   • 编译Carla的UE4插件模块。
   • 最终启动UE4编辑器，并打开Carla的示例地图Town10。

   如果一切顺利，你将看到UE4编辑器窗口打开，并加载一个城市环境。这意味着Carla服务器已经成功运行起来了。

4.4 配置Python环境与测试

我们不应该将Carla的Python包直接安装到系统Python中。使用虚拟环境是更干净的做法。

1. 创建并激活虚拟环境：

   cd ~ python3 -m venv carla-env source carla-env/bin/activate

2. 安装Carla的Python包： 使用前面编译生成的.egg文件进行安装。你需要先安装pip的一个工具setuptools。

   pip install -U pip setuptools wheel pip install ~/carla/PythonAPI/carla/dist/carla-0.9.13-py3.8-linux-x86_64.egg

   实操心得：有时直接安装.egg文件可能会因为路径问题失败。一个更稳妥的方法是，先将其解压到一个目录，然后用pip install -e /path/to/extracted/dir以可编辑模式安装。但直接安装.egg是最标准的方式，优先尝试。

3. 安装其他依赖： Carla的Python示例脚本还需要一些额外的库。

   pip install pygame numpy opencv-python

4. 运行一个简单的Python客户端测试： 保持UE4编辑器运行着Carla服务器（即那个城市场景窗口）。 在另一个终端，激活虚拟环境，运行一个示例脚本：

   cd ~/carla source ~/carla-env/bin/activate python3 PythonAPI/examples/manual_control.py

   如果成功，你会看到一个PyGame窗口，里面是车辆的第三人称视角，并且你可以用方向键或WASD控制车辆在城市里行驶。这标志着从Python客户端到Carla服务器的整个链路完全打通。

5. 核心问题排查与解决方案实录

即便严格按照上述步骤，你也可能遇到一些“特色”问题。下面是我在安装过程中遇到并解决的一些典型难题。

5.1 UE4编译过程中的常见错误

• 错误：The required library ‘libudev.so.0’ could not be found原因：Ubuntu 20.04及更高版本中，libudev库的版本是libudev.so.1，但UE4的一些第三方依赖仍寻找旧版本。解决：创建一个符号链接来“欺骗”系统。

  sudo ln -sf /lib/x86_64-linux-gnu/libudev.so.1 /lib/x86_64-linux-gnu/libudev.so.0

  然后重新运行./GenerateProjectFiles.sh和make。

• 错误：编译ShaderCompileWorker时卡住或失败原因：可能是临时文件冲突或资源不足。解决：

  1. 尝试清理后单独编译：make ShaderCompileWorker -j 4。
  2. 如果还不行，尝试完全清理UE4中间文件，然后从头Setup和GenerateProjectFiles。清理命令：在UE4源码根目录，make clean或直接删除Engine/Intermediate/和Engine/DerivedDataCache/目录（比较粗暴但有效）。

• 错误：fatal error: ‘asio/ssl.hpp’ file not found或类似Boost库错误原因：系统安装的Boost库版本或组件不完整。解决：确保安装了libboost-all-dev。如果问题依旧，Carla的make脚本其实会自己构建Boost的特定版本。确保你在编译Carla前，已经成功运行了git submodule update，它下载的依赖里包含了Boost源码。

5.2 Carla编译与运行问题

• 问题：运行make PythonAPI时，卡在Building Boost.Python...很久原因：这是正常现象。Carla需要编译一个定制版本的Boost，特别是Boost.Python组件，这个过程非常耗时（可能30分钟以上）。请耐心等待，只要不报错就不要中断它。

• 问题：make launch成功后，UE4编辑器打开但地图是空的，或者控制台有大量红色错误原因：最常见的原因是Carla插件没有正确编译或UE4引擎路径不对。解决：

  1. 确认UE4_ROOT环境变量设置正确，并且指向的是你编译成功的UE4根目录。
  2. 检查~/carla/Unreal/CarlaUE4/目录下的CarlaUE4.uproject文件。用文本编辑器打开它，看"EngineAssociation"字段的值是否是一个有效的引擎版本标识符（如"4.26"）。有时需要右键点击这个.uproject文件，选择“切换UE4版本”来重新关联。
  3. 在UE4编辑器的“输出日志”面板中查看具体错误信息。如果是缺少模块，可以尝试在Carla目录下运行make clean，然后重新make launch。

• 问题：Python客户端无法连接到服务器 (timeout错误)原因：

  1. 服务器没启动：确保UE4编辑器中的Carla场景正在运行（不是处于暂停或编辑模式）。
  2. 端口冲突：Carla默认使用2000端口（世界端口）和2001端口（RPC端口）。检查是否有其他程序占用。
  3. 防火墙：Ubuntu的UFW防火墙可能阻止了连接。可以临时禁用测试：sudo ufw disable（测试后记得重新启用：sudo ufw enable）。解决：在Python脚本中，创建客户端时指定主机和端口：

  client = carla.Client('localhost', 2000) client.set_timeout(10.0) # 设置10秒超时

5.3 性能与稳定性优化

• UE4编辑器运行卡顿：

  • 在UE4编辑器的“编辑” -> “编辑器偏好设置” -> “性能”中，可以关闭一些实时渲染功能，如“实时渲染预览”。
  • 将编辑器视口的“显示”模式从“画质”调整为“性能”模式。
  • 确保你的NVIDIA驱动设置中，性能模式为“最高性能”，而不是“自适应”。

• Carla仿真步进慢：

  • 在Carla的Python脚本中，设置固定的时间步长（Fixed Delta Seconds）可以提高物理模拟的确定性和性能。在服务器启动时可以通过命令行参数或world.tick()时设置。
  • 减少场景中动态物体（如车辆、行人）的数量，它们会显著增加计算负荷。

6. 后续开发环境配置建议

成功安装并运行Carla后，为了更高效地进行开发，我建议你配置好以下工具和环境。

1. 集成开发环境 (IDE):

   • Visual Studio Code: 轻量且强大，通过Python扩展和C++扩展，可以很好地编写Carla的Python客户端和修改C++源码。配置好launch.json和tasks.json可以实现一键运行和调试脚本。
   • CLion 或 Qt Creator: 如果你需要深度修改Carla的C++源码或UE4插件，这些专业的C++ IDE在代码导航、重构和调试方面更有优势。需要配置好CMake项目。

2. 版本控制: 你对Carla源码的任何本地修改，都应该在一个独立的分支上进行。建议fork官方的Carla仓库到你的GitHub账户，然后克隆你自己的fork进行开发。这样便于管理自己的修改，也方便未来与上游版本同步。

3. Docker辅助开发（可选）: 如果你需要纯净的编译环境，或者需要在不同Carla版本间切换，可以考虑使用Carla官方提供的Docker镜像来编译特定的组件（如LibCarla）。但这通常用于持续集成或特定部署场景，对于日常开发，直接在宿主机上操作更直观。

4. 文档与社区:

   • Carla官方文档: 详细阅读，特别是Python API reference和教程。
   • Carla GitHub Issues: 遇到任何奇怪的问题，先去这里搜索，大概率已经有人遇到并讨论了解决方案。
   • Unreal Engine 官方文档和论坛: 当需要深入理解UE4的Actor、Component、蓝图等概念以扩展Carla时，这里是宝库。

整个安装过程确实繁琐，但一旦环境搭建成功，它就成为了一个强大的、可定制的自动驾驶研究沙盒。你可以修改传感器模型、创建新的交通场景、测试不同的控制算法，所有这一切都基于一个视觉上极其逼真的仿真平台。记住，在Linux下进行这类大型开源项目的编译，就是一个不断遇到问题、搜索、尝试和解决问题的过程，耐心和细致的记录是你的最佳伙伴。希望这份详尽的指南能帮你扫清障碍，顺利开启你的Carla仿真之旅。如果在某个步骤遇到了本指南未涵盖的诡异错误，不妨休息一下，理清思路，从环境变量、依赖版本、日志文件这几个最可能出问题的地方重新检查一遍，往往会有新的发现。