企业官网建设流程全解析

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命令查看磁盘使用情况。
• GPU：Carla是一个图形密集型应用。虽然编译过程不强制要求独立显卡，但后续运行模拟器时，一块性能足够的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.email@example.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.sh

Setup.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 ~/.bashrc

4.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。

1. 使用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

2. 手动寻找备用源：有时，这些资源包会被热心的社区成员同步到国内的网盘或镜像站。你可以在Carla的中文社区、论坛或相关技术博客中搜索 “Carla 0.9.4 资源包 国内镜像” 等关键词。找到后，用wget或aria2c下载到~/carla-dev/carla目录下。

3. 解压资源包：无论通过哪种方式下载到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 "numpy<1.24" # 对于Python 3.8，安装1.23.x系列通常是安全的 # 然后安装Carla的其他依赖 (carla-venv) python -m pip install --upgrade -r ${CARLA_ROOT}/PythonAPI/carla/requirements.txt

requirements.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 launch

make launch命令会启动Unreal Engine编辑器，并加载Carla项目。第一次启动会非常慢，因为编辑器需要编译Shader（着色器）和构建网格距离场等。你会看到编辑器窗口弹出，底部有编译进度条。请耐心等待，直到编辑器界面完全加载，并且左下角的编译提示消失。

在编辑器中，你可以点击顶部工具栏的“播放”按钮来启动仿真服务器。此时，Carla服务器就开始在本地运行，并监听默认的端口（通常是2000和2001）。

6. 测试与验证

编译完成并启动服务器后，我们必须进行测试，确保一切功能正常。

6.1 基础功能测试

保持Unreal Editor中的仿真处于运行状态（即点击了Play按钮）。打开一个新的终端窗口。

1. 激活虚拟环境并运行示例脚本：

   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的仿真窗口中看到汽车和行人在街道上移动。

2. 运行传感器示例： 再开一个终端，运行一个带有摄像头的示例。

   cd ~/carla-dev source carla-venv/bin/activate cd ${CARLA_ROOT}/PythonAPI/examples (carla-venv) python3 manual_control.py

   这会弹出一个PyGame窗口，显示ego车辆（你控制的车）的摄像头画面，你可以用方向键或WASD控制车辆。

6.2 常见问题与排查技巧

即使严格遵循步骤，你也可能遇到一些问题。下表汇总了我遇到的一些典型问题及解决方案：

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的官方论坛或相关的开发者社区搜索，通常你遇到的坑，早已有前辈填平了。