📚 课程目录第4章环境搭建与快速上手

4. 环境搭建与快速上手

ScenarioRunner 是构建在 CARLA 仿真器之上的场景执行引擎，它本身并不包含仿真世界，而是通过 PythonAPI 与 CARLA Server 通信，加载 OpenSCENARIO 或自定义场景并驱动车辆、行人、传感器完成测试。因此环境搭建的核心逻辑是：先让 CARLA 跑起来，再让 ScenarioRunner 找到它。本节围绕安装、依赖、首个场景运行与排障四条主线展开。

一、核心原理：三层依赖关系

理解环境结构比记住命令更重要。整个运行链路可以拆成三层：最底层是 CARLA Server（C++ 仿真进程，负责物理、渲染、地图），中间层是 CARLA PythonAPI（客户端库，负责与 Server 通信），最上层是 ScenarioRunner（场景解析与执行逻辑）。三者版本必须匹配，否则会出现连接失败、API 缺失或场景无法解析等问题。

二、安装流程与 Python 依赖配置

推荐使用 Ubuntu 20.04/22.04 环境。CARLA 官方提供预编译包，解压即用；ScenarioRunner 从 GitHub 克隆后需要安装依赖。关键步骤是设置 CARLA_ROOT 与 PYTHONPATH，让 Python 能找到 carla 模块和 ScenarioRunner 包。

# 1. 启动 CARLA Server（无渲染模式适合服务器）
./CarlaUE4.sh -RenderOffScreen -carla-port=2000

# 2. 安装 CARLA PythonAPI（版本必须与 Server 一致）
pip install carla==0.9.13

# 3. 克隆 ScenarioRunner
git clone -b v0.9.13 https://github.com/carla-simulator/scenario_runner.git
cd scenario_runner

# 4. 安装依赖
pip install -r requirements.txt

# 5. 配置环境变量
export CARLA_ROOT=/home/user/CARLA_0.9.13
export PYTHONPATH=$PYTHONPATH:$CARLA_ROOT/PythonAPI/carla
export PYTHONPATH=$PYTHONPATH:$CARLA_ROOT/PythonAPI/carla/dist/carla-0.9.13-py3.8-linux-x86_64.egg
export PYTHONPATH=$PYTHONPATH:$(pwd)

若使用 conda，建议单独创建 Python 3.8 环境，避免系统 Python 与 CARLA egg 包冲突。安装完成后可用 python -c "import carla; print(carla.__version__)" 验证。

三、运行第一个预定义场景

ScenarioRunner 自带大量预定义场景，位于 srunner/scenarios/ 目录。最经典的入门场景是 FollowLeadingVehicle（跟随前车），它不依赖复杂地图，适合验证环境是否正常。

# 启动场景：前车突然减速，测试主车是否跟随
python scenario_runner.py \
  --scenario FollowLeadingVehicle \
  --route srunner/data/routes_debug.xml \
  --reloadWorld

# 运行 OpenSCENARIO 格式场景
python scenario_runner.py \
  --openscenario srunner/examples/FollowLeadingVehicle.xosc \
  --reloadWorld

运行成功后，终端会输出场景加载、Actor 生成、判定结果等信息。典型日志如下：

[INFO] Loading scenario FollowLeadingVehicle
[INFO] Scenario loaded successfully
[INFO] Spawning ego vehicle at spawn point 10
[INFO] Spawning leading vehicle
[INFO] Scenario running...
[INFO] Scenario result: SUCCESS
[INFO] Criteria: FollowLeadingVehicle - min distance 8.2m

四、常见环境问题排查清单

环境问题大多集中在连接、版本、路径三类。下表汇总了高频故障与处理方式，建议按顺序排查。

现象	可能原因	排查与解决
Connection refused / timeout	CARLA Server 未启动或端口被占用	确认 `CarlaUE4.sh` 已运行，检查 2000 端口，必要时更换 `--carla-port`
ModuleNotFoundError: carla	PYTHONPATH 未包含 egg 包	检查 `PYTHONPATH`，确认 egg 文件路径与 Python 版本匹配
版本不匹配警告	Server 与 PythonAPI 版本不一致	统一使用同一版本号，如 0.9.13
场景加载失败	route 或 xosc 路径错误	使用绝对路径，确认文件存在且格式正确
渲染卡顿或崩溃	GPU 资源不足	使用 `-RenderOffScreen` 或降低画质

不要混用不同版本的 CARLA 与 ScenarioRunner。例如 CARLA 0.9.13 搭配 ScenarioRunner 0.9.9，可能出现 API 缺失或场景解析异常。版本号必须严格对应。

五、复盘：环境搭建的关键认知

环境搭建不是一次性任务，而是后续所有场景测试的基础。建议把环境变量写入 ~/.bashrc，并用一个最小脚本验证链路：启动 Server → 导入 carla → 连接 world → 运行 ScenarioRunner。只要这条链路稳定，后续的 OpenSCENARIO 编写、批量测试、结果分析才有可靠前提。遇到问题时，优先确认“Server 是否在跑、版本是否一致、路径是否正确”这三件事，绝大多数故障都能快速定位。