环境搭建：CARLA的安装配置（Windows/Linux）、Python API环境、依赖库及常见安装问题排查

CARLA仿真器的环境搭建是整个自动驾驶开发流程的基石。无论是进行传感器仿真、规划算法验证，还是构建硬件在环（HIL）测试台架，一个稳定、纯净且版本匹配的环境是后续所有工作的前提。本章将深入拆解在Windows与Linux双平台下的安装流程、Python API环境的构建、核心依赖库（NumPy、PyTorch）的配置策略，并针对高频安装故障提供系统性的排查方法论。

上图展示了CARLA环境搭建的整体架构关系。从平台层（Windows/Linux）出发，核心引擎与Python API客户端通过本地网络（默认TCP 2000端口）通信，而Python API的运行依赖NumPy、PyTorch等科学计算库。配置层（环境变量）是连接引擎与API的桥梁，最终通过验证与排障环节确保整个链路畅通。理解这张图，有助于在后续安装过程中快速定位问题所在层级。

2.1 核心原理：CARLA的软件架构与版本匹配机制

CARLA基于Unreal Engine 4（UE4）构建，采用客户端-服务器（Client-Server）架构。服务器端（CarlaUE4）负责渲染仿真环境、物理计算和传感器数据生成；客户端（Python API）通过TCP协议发送控制指令并接收传感器数据。这种架构决定了环境搭建的两个关键点：引擎版本与Python API版本必须严格对应，以及网络通信（本地回环）必须畅通。

版本匹配是CARLA环境搭建中最容易忽视却影响最大的因素。CARLA官方发布版本（如0.9.15）会同时提供对应的Python API包（carla-0.9.15-cp38-cp38-win_amd64.whl）。如果使用pip安装了不匹配的API版本，即使引擎正常启动，客户端也会报出AttributeError或ImportError，因为API定义与服务器端的RPC接口不一致。

import carla
print(carla.__version__)  # 应输出与服务器一致的版本号

另一个核心原理是路径与环境的解耦。CARLA引擎本身不依赖Python环境，但Python API需要找到carla模块。这通过设置PYTHONPATH环境变量指向CARLA安装目录下的PythonAPI/carla/dist文件夹来实现。理解这一点，就能明白为什么有时引擎能启动但Python导入失败——往往是PYTHONPATH未正确配置。

2.2 操作流程：Windows与Linux双平台安装实战

以下操作流程以CARLA 0.9.15版本为例，该版本是目前自动驾驶教学与科研中最稳定的版本之一。不同小版本（如0.9.13、0.9.14）的安装步骤基本一致，但依赖库要求略有差异。

2.2.1 Windows平台安装步骤

1. 硬件预检：确认NVIDIA显卡驱动版本≥470.0（建议使用Studio驱动），显存≥6GB（推荐8GB以上）。在命令行执行nvidia-smi查看驱动信息。
2. 下载CARLA压缩包：从官方GitHub Releases页面下载CARLA_0.9.15.tar.gz（约20GB），解压到无中文、无空格的路径，例如D:\CARLA_0.9.15。
3. 启动服务器：进入解压目录，双击CarlaUE4.exe。首次启动会进行着色器编译，耗时5-15分钟，属正常现象。看到UE4编辑器窗口出现且命令行显示Listening for connections on port 2000即表示启动成功。
4. 安装Python API：打开Anaconda Prompt或CMD，执行：

   pip install numpy
   pip install D:\CARLA_0.9.15\PythonAPI\carla\dist\carla-0.9.15-cp38-cp38-win_amd64.whl

   注意：如果Python版本不是3.8，需要从源码编译或使用conda创建3.8虚拟环境。
5. 配置环境变量：右键“此电脑”→“属性”→“高级系统设置”→“环境变量”，新建用户变量CARLA_ROOT指向D:\CARLA_0.9.15，并在PYTHONPATH中添加%CARLA_ROOT%\PythonAPI\carla\dist。

2.2.2 Linux平台安装步骤（Ubuntu 20.04）

1. 系统依赖安装：

   sudo apt-get update
   sudo apt-get install -y wget unzip build-essential
   sudo apt-get install -y libomp5 libpng16-16 libtiff5 libjpeg8-dev

2. 下载与解压：

   wget https://carla-releases.s3.us-east-005.backblazeb2.com/Linux/CARLA_0.9.15.tar.gz
   tar -xzf CARLA_0.9.15.tar.gz -C ~/carla

3. 启动服务器：

   cd ~/carla
   ./CarlaUE4.sh -quality-level=Low

   -quality-level=Low参数可降低GPU负载，适合无独立显卡的服务器环境。
4. 安装Python API：

   pip3 install numpy
   pip3 install ~/carla/PythonAPI/carla/dist/carla-0.9.15-cp38-cp38-linux_x86_64.whl

5. 设置环境变量：编辑~/.bashrc，添加：

   export CARLA_ROOT=~/carla
   export PYTHONPATH=$CARLA_ROOT/PythonAPI/carla/dist:$PYTHONPATH

   然后执行source ~/.bashrc。

2.3 依赖库配置：NumPy与PyTorch的版本协同策略

CARLA的Python API依赖NumPy进行传感器数据的数组化处理，而PyTorch则用于深度学习模型的推理与训练（如自动驾驶感知模型）。两者与CARLA的协同配置需要遵循以下原则：

PyTorch的安装需要特别注意CUDA版本匹配。在命令行执行nvidia-smi查看驱动支持的CUDA版本，然后访问PyTorch官网选择对应的安装命令。例如，驱动支持CUDA 11.7时，使用pip install torch==1.13.1+cu117 --extra-index-url https://download.pytorch.org/whl/cu117。如果驱动版本较新（支持CUDA 12.x），则直接安装默认的PyTorch 2.x版本即可。

2.4 案例拆解：一次完整的安装排障闭环

背景与约束：某自动驾驶团队在Ubuntu 20.04服务器上部署CARLA 0.9.14，用于HIL仿真测试。服务器配置为Intel Xeon E5-2680 v4（无集成显卡）、NVIDIA Quadro P4000（8GB显存）、64GB内存。团队需要在无显示器环境下通过SSH远程使用CARLA。

初始现象：执行./CarlaUE4.sh后，终端输出Segmentation fault (core dumped)，服务器进程立即退出。同时，Python客户端连接时报Connection refused错误。

关键日志与指标：查看~/carla/CarlaUE4/Saved/Logs/CarlaUE4.log，发现最后几行包含Fatal error: [File:Unknown] [Line: 0] Cannot open display。进一步检查nvidia-smi，确认GPU驱动正常，但DISPLAY环境变量为空。

分析判断过程：CARLA的UE4引擎默认需要图形显示环境。在无显示器的服务器上，必须使用虚拟显示技术（Xvfb）或设置CARLA为无头模式（Headless）。CARLA 0.9.14支持-RenderOffScreen参数，但该参数需要配合LIBGL_ALWAYS_INDIRECT=0使用。

实际操作步骤：

1. 安装Xvfb：sudo apt-get install -y xvfb
2. 使用Xvfb启动CARLA：

   xvfb-run -s "-screen 0 1280x720x24" ./CarlaUE4.sh -RenderOffScreen -quality-level=Low

3. 验证服务器启动：在另一个终端执行python3 -c "import carla; c=carla.Client('localhost',2000); print(c.get_server_version())"，输出0.9.14表示连接成功。

结果对比：使用Xvfb后，CARLA服务器稳定运行超过72小时，CPU占用率约45%，GPU显存占用约3.2GB（用于离屏渲染）。相比有显示器环境，性能损失约10%，但满足了远程无头部署的需求。

风险与代价：离屏渲染模式下，CARLA的传感器数据（尤其是摄像头图像）的帧率会略有下降（从60FPS降至约50FPS）。对于HIL测试中需要高帧率视觉数据的场景，建议使用虚拟显示器（如VirtualGL）或增加GPU资源。

复盘经验：无头服务器部署CARLA时，优先尝试-RenderOffScreen参数；如果失败，再使用Xvfb。同时，务必在启动前检查DISPLAY变量和LIBGL_ALWAYS_INDIRECT设置。此外，CARLA的日志文件是排障的第一手资料，应养成查看~/carla/CarlaUE4/Saved/Logs/目录的习惯。

2.5 常见误区与总结复盘

在CARLA环境搭建过程中，以下误区会导致大量时间浪费，需要特别警惕：

• 误区一：盲目升级NumPy到最新版。NumPy 1.24+移除了np.float、np.int等别名，而CARLA 0.9.x的API内部仍在使用这些属性，导致AttributeError: module 'numpy' has no attribute 'float'。解决方案是固定NumPy版本为1.23.x。
• 误区二：忽略Python版本要求。CARLA官方whl包仅支持Python 3.8（部分新版本支持3.9）。使用Python 3.10或3.11会导致ImportError: DLL load failed（Windows）或undefined symbol（Linux）。务必使用conda创建3.8环境。
• 误区三：在Windows下使用WSL运行CARLA。WSL（Windows Subsystem for Linux）不支持GPU直通（除非使用WSL2 + Windows 11的GPU-PV），导致CARLA无法启动或渲染异常。建议在Windows原生环境或双系统Linux下运行。
• 误区四：忽略防火墙对TCP 2000端口的限制。Windows防火墙或Linux iptables可能阻止本地回环连接。如果客户端报Connection refused，先检查netstat -an | grep 2000确认端口监听状态，再检查防火墙规则。