Windows下源码编译CARLA并导入RoadRunner地图的完整指南-平芜编程栈

如果你要在 Windows 上从源码自己编译 CARLA，还打算把 MathWorks RoadRunner 做的路网完整导入进去跑自动驾驶仿真，那这篇文章就是冲着你来的。CARLA 的源码安装默认资料大多讲 Linux 和 Docker，Windows 这条路文档少、坑多，很多教程到一半就断在某个编译错误上。我前前后后折腾了一周，从环境配到编译，再从 RoadRunner 插件导出到地图导入，最终在本地把一套完整流程跑通。这篇就把整个过程拆开讲清楚，包括我踩过的坑和那些文档里不会写的细节。

整个过程适合有一定 C++、Python 基础，想在本地建自定义仿真地图，或者打算改 CARLA 源码做传感器、车辆动力学开发的人。如果你只是想快速跑 CARLA 官方案例，直接下载预编译包更省事；但只要是涉及到“源码级修改”或“RoadRunner 自定义地图深入集成”，按下面的路径走会少走很多弯路。

1. 为什么在 Windows 上源码编译：方案选型与适用场景

1.1 源码安装与预编译安装怎么选

CARLA 官方提供两种主流使用方式：一种是直接下载编译好的安装包，另一种是从源码自行编译。预编译包最大的优势是快，解压就能跑，Python API 也现成，适合验证功能和学基础操作。但它也有很明显的边界：你只能使用官方固定的引擎版本和编译选项，改不了底层 C++ 代码，也没法把自定义的 RoadRunner 地图资产深透地接入编辑器工程里。

源码编译最大的价值在于“可控”。你可以改 UE4 的渲染管线，可以往 CARLA 里塞自定义的传感器模型，也可以在编译阶段就把 RoadRunner 导出的地图打进去，而不是只能在运行期通过 OpenDRIVE 临时生成。缺点同样明显：编译时间长、环境依赖极其敏感、磁盘和内存要求高，一旦路径和工具链版本对不上，报错会让你怀疑人生。

我这次的场景很明确：需要把 RoadRunner 做的本地道路网在 CARLA 里面变成稳定的仿真环境，并且后续还可能改交通信号灯逻辑和传感器布置。所以选择源码安装，而不是临时用 Python API 里的generate_opendrive_world凑合。后者的确能从 OpenDRIVE 生成路网，但它没有精细的 3D 视觉模型，RoadRunner 里做的标线、护栏、建筑边界全都用不上，和“地图导入”的要求差得太远。

1.2 硬件与系统要求

在 Windows 上源码编译 CARLA，本质上是在编译一个定制过的 Unreal Engine 工程，所以硬件一定不要省。我实测下来比较合理的配置是：

CPU 不低于 8 核，12 核以上编译时间能明显缩短；
内存至少 16GB，32GB 更保险，因为 UE 编译时多个进程同时跑，内存占用经常超过 12GB；
显卡推荐 NVIDIA RTX 系列，显存 8GB 以上，毕竟后面的车流渲染和摄像头传感器仿真都吃显存；
磁盘留出至少 80GB 的空间，我装了源码、UE4、内容资产和中间缓存后，实际占用接近 100GB，建议直接用 NVMe SSD，否则编译和资源加载会等得很痛苦；
系统建议 Windows 10 专业版或 Windows 11，64 位，关闭第三方杀毒软件对目录的实时扫描。

这里有个很容易被忽视的点：工程路径里不能有中文，也不能有空格。Carla 源码、Unreal Engine 和 RoadRunner 导出目录最好都放在简单英文路径下，比如D:\CARLA\carla、D:\CARLA\UE4。我一开始放在带空格的Program Files相关目录里，编译时 UE 的批处理脚本直接报路径找不到，排查了好久才反应过来。

1.3 版本组合决定了后面所有流程

CARLA 不同版本绑定的 UE4 分支和 Python 版本都不一样，千万不能随便配。以 0.9.15 版本为例，它绑定的是 CARLA 官方的 Unreal Engine 4.26 分支，Python 推荐使用 3.8 的 64 位版本。如果你拉的是 master 分支或更新版本，可能需要换 UE 分支，所以第一步就要把版本锁死。

RoadRunner 那边也类似，不同年份版本对 CARLA 插件的适配程度有差异。我用的 RoadRunner R2022b 和 CARLA 0.9.15 组合还算稳定。建议在动手前先确认你拿到的 RoadRunner 插件是否匹配当前 CARLA 版本，不匹配的话导出流程会多出很多手工修正步骤。

2. 编译前的完整环境准备

2.1 需要提前准备的依赖清单

源码编译 CARLA 不完全等同于编译普通 C++ 工程，它涉及 UE4、Python API、第三方库和内容资产四块。下面这些依赖最好一次性装齐：

Visual Studio 2019，必须勾选“使用 C++ 的桌面开发”工作负载，并且安装 Windows SDK 10.0.18362 或更高版本；
Git for Windows，同时启用 Git LFS，因为 CARLA 仓库切换分支时有大文件需要拉取；
CMake 3.20 以上，CARLA 的构建流程会调用 CMake 生成项目文件；
Python 3.8 64 位，并安装pip install pygame numpy，否则后面的 PythonAPI 示例跑不起来；
Unreal Engine 4.26 定制版，注意一定不是从 Epic 官方 Launcher 里装的原版 UE；
CARLA 0.9.x 源码包，从 GitHub 拉取指定分支；
RoadRunner 软件本体，以及对应的 CARLA 导出插件。

听起来有点多，但每一项都是必须的。漏了 CMake 或者装了 32 位 Python 这类小事，通常不会立刻报错，而是在编译到一半或者运行 Python 脚本时才突然冒出来，出问题的时间和定位成本反而更高。

2.2 获取正确的 Unreal Engine 4.26 分支

这里特别花一段来说，是因为很多人卡在最前面。CARLA 不是用任何 UE4 版本都能编译的，它基于一版自定义的 Unreal Engine Fork，里面带了 CARLA 团队针对传感器和地图做的引擎级改动。这个仓库通常从 CARLA 官方 GitHub 组织下获取，分支名称会和当前 CARLA 版本对应。

获取的通用方式是在 CARLA 工程目录旁边建一个 UE4 目录，然后用 Git 拉取对应分支。比如在D:\CARLA\下执行：

git clone -b 0.9.15 https://github.com/carla-simulator/carla.git git clone -b ue4.26-carla https://github.com/carla-simulator/UnrealEngine.git UE4

注意，不同时期的官方分支命名会有差别，具体还是以当前 CARLA 文档里的分支名称为准。拉取 UE 源码之前，需要你先在 Epic Games 官网同意 UE 的最终用户协议，并把 GitHub 账号和 Epic 账号做关联绑定，GitHub 会从这个仓库地址的访问权限上校验。这个步骤绕不开，只能提前弄好，否则git clone时会直接 403。

UE4 拉下来之后，不要急着编译整个 UE4，先用它自带的Setup.bat把第三方预编译库和依赖初始化一遍。这一步在 Windows 上会下载一堆零碎的 DLL 和源码包，耗时取决于网络，也可能失败，多跑几次一般能过。

2.3 Visual Studio 与 Python 环境配置要点

Visual Studio 2019 的安装有很多可以精简的地方，但核心组件别省。我建议至少勾选“使用 C++ 的桌面开发”和“CMake 工具”，SDK 组件选 Windows 10 SDK 最新兼容版本。如果你之前装过 VS2022，也不要直接用，UE4.26 官方的 VS 版本匹配是 VS2019，用 VS2022 打开工程会有一堆头文件和平台工具集不兼容问题，除非你自己改工具集，否则不建议冒险。

Python 环境我个人不建议用在 Anaconda 里。原因很简单，CARLA 的 PythonAPI 包含一个编译好的carla扩展模块，它和官方 Python 版本直接绑定，装到 conda 环境里经常出现 DLL 加载错误。我最后是单独装了一个官方 Python 3.8.10，然后直接设置PYTHONPATH指向 CARLA 的PythonAPI/carla目录。这样不仅编译干净，后面跑client = carla.Client(...)也不会报莫名其妙的_imp相关错误。

环境变量方面，需要把UE4_ROOT指向你拉取 UE4 的根目录，这样 CARLA 的构建脚本才知道去哪里找引擎。比如：

set UE4_ROOT=D:\CARLA\UE4

这一步设置错，后面生成 VS 工程文件时会直接找不到 Engine 路径报错。

3. Windows 下 CARLA 源码编译全程实录

3.1 调整目录结构和预期结果

源码编译之前先把目录结构理清楚，CARLA 构建脚本对相对路径非常敏感。我最终的目录结构大致是这样：

D:\CARLA\ UE4\ Engine\ GenerateProjectFiles.bat carla\ PythonAPI\ Unreal\ CarlaUE4\ Tools\ Setup.bat

CARLA 源码本身包含 Unreal 工程，所以构建时会在Unreal/CarlaUE4下生成 VS 工程文件。启动后最终出现的可执行文件是CarlaUE4.exe，它其实就是定制过的 UE4 编辑器/游戏客户端，CARLA 所有仿真逻辑都跑在这个进程里。

我这次的目标是“带编辑器编译”，因为这关系到后面能不能通过 UE 编辑器把 RoadRunner 导出的 FBX 资产正确打包进地图。如果只编译游戏目标，虽然能跑起来，但地图资产导入流程会受限。

3.2 构建命令逐个拆解

进入 CARLA 源码根目录后，第一步运行Setup.bat。这个脚本会下载并解压 CARLA 内容资产（CarlaContent），还会调用 UE 相关工具初始化项目。一个常见的坑是：脚本下载大文件过程中被中断。不要慌，直接重新执行脚本，它会断点续传或跳过已完成的步骤，多跑几次会通过。

第二步运行GenerateProjectFiles.bat。它会把Unreal/CarlaUE4目录下的.uproject文件生成成 Visual Studio 解决方案，也就是CarlaUE4.sln。生成完成后，用 Visual Studio 2019 打开这个解决方案，在解决方案配置里选择Development Editor，平台选择Win64，然后对CarlaUE4项目执行生成。

在 VS 里生成的时候注意一点：目标选择看起来有好几个，比如CarlaUE4、CarlaUE4Editor、CarlaUE4Client等。我们要编译的是带编辑器功能的CarlaUE4主目标，等待时间会非常长，第一次全量编译在我这台 12 核机器上差不多跑了 1 小时 40 分钟，期间 CPU 持续满载，散热不好的机器要提前清灰。

编译结束后的验证方式也很直接，去Unreal\CarlaUE4\Binaries\Win64下找到可执行文件启动：

CarlaUE4.exe -quality-level=Low

这里先说一下：首次启动会加载大量 UE 资产，窗口可能需要几十秒甚至更久才有反应，这不一定是死机。如果看到日志里出现类似Configuring Carla...等内容，说明引擎正在初始化，等它稳定输出就行。

3.3 首个启动验证与常见编译报错

第一次编译最容易遇到的几个错误，我按出现频率排一下：

缺少 Windows SDK 版本：构建脚本会报找不到某个 SDK 版本，去 Visual Studio Installer 里确认 SDK 已安装即可；
LNK 错误：通常是第三方库没有完整下载，重新跑Setup.bat；
Python 相关错误：如果 PythonAPI 编译失败，重点检查安装的是官方 Python 而不是 conda 版本，并且路径已加入系统的PATH；
UE4 的 Shader 编译错误：这是显卡驱动或硬件问题比较多，建议升级到官方最新的 Game Ready 驱动，同时关闭其他占用显存的程序。

启动验证通过后，CARLA 服务端会在命令行终端里输出监听 2000 端口的信息。此时另开一个 Python 终端，先手动设置PYTHONPATH：

set PYTHONPATH=D:\CARLA\carla\PythonAPI\carla\dist;D:\CARLA\carla\PythonAPI\carla\agents

然后执行一个最简单的 Python 脚本测试连接：

import carla client = carla.Client("127.0.0.1", 2000) client.set_timeout(10.0) world = client.get_world() print(world.get_map().name)

如果打印出当前地图名称，恭喜，CARLA 源码版已经活了。接下来才到 RoadRunner 地图的部分。

4. RoadRunner 地图制作与 CARLA 插件配置

4.1 RoadRunner 核心概念与地图结构

RoadRunner 是 MathWorks 出品的道路建模工具，它的核心思路是“以车道网络为骨架”，在编辑器里画道路中心线，设置车道数、宽度、连接关系，系统会自动生成符合 OpenDRIVE 标准的道路拓扑。同时它还能在路网模型上追加红绿灯、停止线、护栏、路沿、路面标线等交通元素。

对于 CARLA 来说，RoadRunner 的真正价值在于：它生成的地图包含两种互补信息。第一种是 OpenDRIVE（.xodr）文件，描述道路几何、车道换道规则、交叉口连接和交通控制元素；第二种是 FBX 三维模型，描述视觉层的地面网格、贴图和交通设施。没有前者，仿真器不知道车辆还能沿什么路线行驶；没有后者，地图就只有逻辑路网，视觉上一片空白。所以导入 CARLA 时，这两类文件都要处理好。

如果只是临时做个路网测试，其实可以直接用 CARLA 的 Python API 从.xodr生成世界，但这样 FBX 的精细模型就用不上。所以正式做地图导入时，我强烈建议走源码编译的完整导入流程，把 RoadRunner 输出的资产全部编译进 CARLA 的地图列表。

4.2 安装 CARLA 导出插件

RoadRunner 默认不会主动把 CARLA 作为导出格式，需要在 RoadRunner 的插件管理里加载 CARLA 专属插件。通常 RoadRunner 安装目录或 MathWorks 官网会提供一个带CarlaExporter字样的插件包，文件后缀一般是.rrplugin。

安装方式分为两种：

直接把.rrplugin文件复制到 RoadRunner 的用户插件目录，例如%APPDATA%\MathWorks\RoadRunner\R2022b\Plugins；
在 RoadRunner 软件内部通过“插件管理器/Add-On Manager”直接加载。

装好插件后，RoadRunner 菜单栏的导出选项里才会出现 CARLA 相关的导出入口。如果找不到，可以检查 RoadRunner 版本和插件版本是否匹配，通常不同年度版本之间插件不能通用。

4.3 建模要点：车道、路口与信号灯

RoadRunner 里画地图比想象中容易，但要让导入后的地图在 CARLA 里“能跑且不穿模”，有几个细节值得注意：

车道宽度尽量和真实道路保持一致，不要为了好看随意改；CARLA 的车道级路段规划完全基于 OpenDRIVE，车道宽度和偏移量直接决定后续车辆换道轨迹；
交叉口必须用 RoadRunner 的 “Junction” 工具生成，不能直接拿两条路拼一个十字路口，否则导出的 OpenDRIVE 缺少交叉口连接关系；
信号灯位置要尽量放在停止线上方，并确认信号灯具的朝向和车道方向一致；RoadRunner 导出时会把信号相位信息转成 CARLA 可识别的交通控制逻辑；
导出前运行一次地图检查（Validate Map），RoadRunner 会高亮断点、重合节点等拓扑问题，这一步能省下后面大量调试时间。

另外，RoadRunner 里的材质命名最好尽量用默认的语义材质，比如路面使用Road或Asphalt，车道线使用LaneMarking等。因为 CARLA 在导入地图时会尝试把材质和交通语义匹配，如果材质名太随意，地图在 CARLA 里可能看起来是紫色或黑色。

5. RoadRunner 地图导入 CARLA 的完整操作

5.1 FBX 与 OpenDRIVE 文件解析

RoadRunner 导出 CARLA 地图时，会得到一个场景导出包，通常包含以下关键文件：

.xodr：OpenDRIVE 路网文件，包含道路、车道、交叉口、信号相位等信息；
.fbx：道路和场景的三维模型；
贴图文件夹：包含路面、标线等纹理贴图；
XML 或 JSON 配置：记录文件关联和参考坐标系。

在导入 CARLA 前，先别急着执行任何工具，把.xodr用文本编辑器打开看一眼，确认里面是否包含<road>、<lane>、<signal>等节点。如果文件里只有空壳，说明 RoadRunner 地图没有构建完整，导出的路网肯定有问题。FBX 文件可以用 Windows 自带的 3D 查看器快速打开预览，检查是否存在明显的几何错位，尤其是原点坐标。

在坐标方面，RoadRunner 默认是 Z 轴向上，这点和 CARLA 一致，但有些早期版本导出设置可能是 Y 轴向上，如果不一致，导入后整个地图会侧躺。遇到这种情况，需要在导出设置里把坐标轴改成 Z-up，或在导入工具中指定-z-up参数。

5.2 导入路网并构建地图包

CARLA 源码工程里通常会带地图导入相关工具，不同版本具体脚本位置有差异，但大致逻辑一样：把 RoadRunner 导出的.fbx复制到 CARLA 的 Content 目录下，把.xodr作为路网数据导入，最后生成一个 CARLA 可用的地图包。

我采用的是先通过 CARLA 源码里Tools下的导入脚本处理，再通过 Unreal 工程重新打包的路线。由于 CARLA 版本会更新脚本名称，建议先到源码的Tools目录里看有哪些带map或import关键字的脚本。常见的有ImportRoadRunnerMap.py、import_rr_map.py等，执行前用--help查看参数，这比直接背命令靠谱。

我当时的导入命令大致是：

python Tools/ImportRoadRunnerMap.py --input D:/RoadRunnerOutput/MyMap --output-dir Unreal/CarlaUE4/Content/Carla/Maps

执行后脚本会完成三件事：把 FBX 转成 UE 的资产并放入 Content 目录；把.xodr解析成 CARLA 的路网数据；生成地图描述文件。导入完成后，重新进入 VS 工程编译一次，确保新地图资产被 UE 的 Content Database 正确索引。这一步不是可选的，直接启动 CARLA 是看不到新地图的，必须把地图资产打包进 Pak 文件才会被运行时加载。

5.3 运行时验证与 Python API 加载地图

编译完成后启动 CARLA，正常等待终端输出端口监听信息。然后在 Python 脚本里获取可用地图列表，确认新地图已经注册：

import carla client = carla.Client("127.0.0.1", 2000) client.set_timeout(30.0) available_maps = client.get_available_maps() for m in available_maps: print(m)

如果列表里有类似Carla/Maps/RoadRunnerDemo这样的地图名，就可以直接加载：

world = client.load_world("Carla/Maps/RoadRunnerDemo") print(world.get_map().name)

加载成功后，我会先在路口附近生成一辆车，再用 spectator 视角绕一圈，重点看三个地方：

路面模型是否和道路线网对齐，有没有明显悬空或嵌入；
红绿灯和停止线是否出现在预期位置；
车辆能否在地图上自由漫游而不频繁偏离到路外。

如果车辆路线异常，大概率是.xodr的路口连接关系有问题，回到 RoadRunner 里调整 Junction 拓扑重新导出。

6. 问题排查与独家避坑清单

6.1 高频问题速查表

我把编译和导入过程中最常遇到的高频问题整理成了一个表，方便你对号入座：

问题现象	可能原因	解决思路
编译到一半报找不到第三方库	UE4 依赖未完整下载	重新执行`Setup.bat`，确认网络稳定
CarlaUE4 启动后黑屏	显卡驱动过旧或 Shader 编译失败	更新显卡驱动，降低画质参数
Python 连接失败	服务端未启动或端口被占用	确认终端有 2000 端口监听信息
导入地图后路面呈紫色	材质语义无法匹配	检查 RoadRunner 材质命名，重新导出
车辆压过路口时路线穿模	OpenDRIVE 交叉口关系缺失	回 RoadRunner 重新生成 Junction
RoadRunner 导出选项里没有 CARLA	插件未安装或版本不匹配	检查插件目录和 RoadRunner 年度版本
地图导入脚本找不到输入文件	路径含有中文或空格	全部改用英文路径

6.2 我反复踩过的三个坑

第一个坑是 Python 环境。我一开始图省事用了 Anaconda，结果import carla一直崩溃，后来在官方 Python 3.8 下直接用才稳定。CARLA 的扩展模块是高度绑定官方 Python 编译 ABI 的，Anaconda 类的发行版对 DLL 查找路径有修改，这也是很多新手反复导入失败的根本原因。

第二个坑是安装了杀毒软件。Windows Defender 或其他国产杀软会把 UE 编译生成的临时可执行文件误认为恶意程序，清理掉之后下次编译又得从头开始。所以编译期间最好把D:\CARLA整个目录加入杀软白名单，或者临时关闭实时防护。

第三个坑是地图导出的原点不一致。RoadRunner 默认场景原点可能离真实路口很远，导入 CARLA 后地图整体偏到角落里，加载后视野里一片空白。解决办法是在 RoadRunner 里把场景原点移动到目标路口附近，再重新导出，或者导入脚本里显式设置地图原点。

6.3 提升编译与导入效率的小技巧

源码编译真的耗时间，但有一些方式可以显著加快节奏：

先使用官方预编译包把 RoadRunner 地图的逻辑路网验证一遍，再动源码编译；这样你至少能确认.xodr和千行级别的路网数据本身没有大问题，避免一边改地图一边等编译；
VS 编译时只生成单一目标，不要首编译就生成全部配置，不然会遇到多个 UE 辅助进程抢占 CPU 的情况，反而更慢；
利用 VS 的增量编译，改动 CARLA 源码或地图资产后，编译时间会大幅缩短；
启动 CARLA 时加-quality-level=Low，能跳过大量高分辨率材质和阴影加载，对调试地图特别友好；
多次导入地图时，建议每次用新地图名，不要覆盖旧地图，这样能对比不同版本 RoadRunner 导出结果之间的差异。

7. 写在最后

我在实际编译时感受最深的一点是：源码安装 CARLA 最难的其实不是技术，而是组合选择。只要版本组合、路径、Python 环境这三样不出错，整个流程基本是能复现的；反过来，如果这三样里有任何一个随意选，后面一定会以各种莫名其妙的方式报错。RoadRunner 导入地图也一样，导出前花点时间把道路拓扑检查好，比导入后调车窗和穿模快多了。

这套流程走通之后，好处是很长一段时间内你都不用担心地图资源不够用。RoadRunner 出道路设计，CARLA 做仿真验证，两者配合可以非常自由地构造封闭园区、高速匝道、乡镇交叉口等各种场景。对我这种经常要验证传感器算法和交通流逻辑的人来说，这套组合基本是我本地开发的主力方案了。如果你也准备在 Windows 上这么干，希望你少走点弯路。