如果你要在 Windows 上从源码自己编译 CARLA还打算把 MathWorks RoadRunner 做的路网完整导入进去跑自动驾驶仿真那这篇文章就是冲着你来的。CARLA 的源码安装默认资料大多讲 Linux 和 DockerWindows 这条路文档少、坑多很多教程到一半就断在某个编译错误上。我前前后后折腾了一周从环境配到编译再从 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 核以上编译时间能明显缩短内存至少 16GB32GB 更保险因为 UE 编译时多个进程同时跑内存占用经常超过 12GB显卡推荐 NVIDIA RTX 系列显存 8GB 以上毕竟后面的车流渲染和摄像头传感器仿真都吃显存磁盘留出至少 80GB 的空间我装了源码、UE4、内容资产和中间缓存后实际占用接近 100GB建议直接用 NVMe SSD否则编译和资源加载会等得很痛苦系统建议 Windows 10 专业版或 Windows 1164 位关闭第三方杀毒软件对目录的实时扫描。这里有个很容易被忽视的点工程路径里不能有中文也不能有空格。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 里装的原版 UECARLA 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_ROOTD:\CARLA\UE4这一步设置错后面生成 VS 工程文件时会直接找不到 Engine 路径报错。3. Windows 下 CARLA 源码编译全程实录3.1 调整目录结构和预期结果源码编译之前先把目录结构理清楚CARLA 构建脚本对相对路径非常敏感。我最终的目录结构大致是这样D:\CARLA\ UE4\ Engine\ GenerateProjectFiles.bat carla\ PythonAPI\ Unreal\ CarlaUE4\ Tools\ Setup.batCARLA 源码本身包含 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-levelLow这里先说一下首次启动会加载大量 UE 资产窗口可能需要几十秒甚至更久才有反应这不一定是死机。如果看到日志里出现类似Configuring Carla...等内容说明引擎正在初始化等它稳定输出就行。3.3 首个启动验证与常见编译报错第一次编译最容易遇到的几个错误我按出现频率排一下缺少 Windows SDK 版本构建脚本会报找不到某个 SDK 版本去 Visual Studio Installer 里确认 SDK 已安装即可LNK 错误通常是第三方库没有完整下载重新跑Setup.batPython 相关错误如果 PythonAPI 编译失败重点检查安装的是官方 Python 而不是 conda 版本并且路径已加入系统的PATHUE4 的 Shader 编译错误这是显卡驱动或硬件问题比较多建议升级到官方最新的 Game Ready 驱动同时关闭其他占用显存的程序。启动验证通过后CARLA 服务端会在命令行终端里输出监听 2000 端口的信息。此时另开一个 Python 终端先手动设置PYTHONPATHset PYTHONPATHD:\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 MapRoadRunner 会高亮断点、重合节点等拓扑问题这一步能省下后面大量调试时间。另外RoadRunner 里的材质命名最好尽量用默认的语义材质比如路面使用Road或Asphalt车道线使用LaneMarking等。因为 CARLA 在导入地图时会尝试把材质和交通语义匹配如果材质名太随意地图在 CARLA 里可能看起来是紫色或黑色。5. RoadRunner 地图导入 CARLA 的完整操作5.1 FBX 与 OpenDRIVE 文件解析RoadRunner 导出 CARLA 地图时会得到一个场景导出包通常包含以下关键文件.xodrOpenDRIVE 路网文件包含道路、车道、交叉口、信号相位等信息.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 重新生成 JunctionRoadRunner 导出选项里没有 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-levelLow能跳过大量高分辨率材质和阴影加载对调试地图特别友好多次导入地图时建议每次用新地图名不要覆盖旧地图这样能对比不同版本 RoadRunner 导出结果之间的差异。7. 写在最后我在实际编译时感受最深的一点是源码安装 CARLA 最难的其实不是技术而是组合选择。只要版本组合、路径、Python 环境这三样不出错整个流程基本是能复现的反过来如果这三样里有任何一个随意选后面一定会以各种莫名其妙的方式报错。RoadRunner 导入地图也一样导出前花点时间把道路拓扑检查好比导入后调车窗和穿模快多了。这套流程走通之后好处是很长一段时间内你都不用担心地图资源不够用。RoadRunner 出道路设计CARLA 做仿真验证两者配合可以非常自由地构造封闭园区、高速匝道、乡镇交叉口等各种场景。对我这种经常要验证传感器算法和交通流逻辑的人来说这套组合基本是我本地开发的主力方案了。如果你也准备在 Windows 上这么干希望你少走点弯路。