1. 项目概述与核心价值如果你是一名自动驾驶领域的开发者或研究者那么Carla这个名字对你来说一定不陌生。作为目前最主流的开源自动驾驶仿真平台之一Carla以其逼真的渲染效果、灵活的传感器配置和丰富的API接口成为了算法验证、数据采集和系统测试的“黄金沙盒”。然而直接从GitHub拉取预编译的二进制版本虽然方便却常常会遇到版本不匹配、功能受限、无法深度定制等问题。尤其是在需要修改底层物理引擎、添加自定义传感器或集成特定算法模块时从源码编译就成了绕不开的一步。我最近在Windows 11系统上使用Visual Studio 2019和Unreal Engine 4.26成功从零编译了Carla 0.9.15版本。整个过程堪称一场“排雷”之旅官方文档的步骤在Win11这个相对较新的环境下以及特定版本的软件组合中存在着大量隐形的“坑”。网上零散的教程要么版本过时要么语焉不详导致我在环境配置、依赖安装和编译过程中耗费了大量时间。因此我决定将这次完整的、踩过无数坑的编译过程记录下来形成一份详尽的避坑指南。这份实录的目标不仅仅是让你“能”编译成功更是让你“清晰、高效、一次成功”地完成编译理解每一个步骤背后的原理并掌握问题排查的核心方法。无论你是刚接触Carla的新手还是需要为特定项目定制化编译的老手这份基于Win11VS2019UE4.26的实战记录都将为你节省大量宝贵的时间。2. 环境准备基石不稳地动山摇编译Carla是一个庞大的系统工程它串联了Python环境、C编译工具链、游戏引擎和一系列第三方库。在开始敲下任何命令之前搭建一个正确、完整且版本匹配的基础环境是成功的一半。这一步的疏忽会导致后续编译错误百出且难以定位根源。2.1 操作系统与基础软件选型Windows 11 22H2 或更新版本这是我们的主战场。Win11引入了WSL2、新的终端等特性但也在文件路径、权限管理和一些系统组件上与Win10有细微差别这些差别正是很多“坑”的来源。确保你的系统已更新到较新的版本并开启开发者模式设置 - 隐私和安全性 - 开发者选项 - 开发人员模式。这能避免后续因权限问题导致的脚本执行失败。Visual Studio 2019 Community/Professional 版本 16.11Carla的C代码编译依赖MSVC工具链。选择VS2019而非更新的VS2022是因为Carla 0.9.15的构建脚本和部分依赖库对VS2019的兼容性经过了更充分的测试。安装时工作负载必须勾选使用C的桌面开发这是核心。Windows 10 SDK (10.0.19041.0) 或更高版本虽然叫Windows 10 SDK但在Win11上编译同样需要。建议安装版本10.0.19041.0这是经过验证与UE4.26兼容较好的版本。对v142生成工具的C CMake工具用于CMake项目的支持。英文语言包某些构建脚本对中文路径支持不佳安装英文包可减少潜在问题。注意安装路径请务必使用纯英文、无空格的路径例如D:\VS2019。将VS安装在系统盘C盘默认路径有时会因Windows Defender实时保护导致编译过程被意外拦截引发难以排查的失败。Python 3.7 (64-bit)Carla的构建脚本和很多工具是用Python编写的。必须使用Python 3.7这是Carla 0.9.15官方明确支持的版本。更高版本如3.8可能会导致distutils等模块不兼容。从Python官网下载安装包安装时务必勾选“Add Python 3.7 to PATH”并将安装路径也设置为纯英文路径如D:\Python37。安装完成后在PowerShell中运行python --version和pip --version确认版本。Git用于克隆Carla仓库及其子模块。安装最新版即可安装过程中选择“Use Git from the Windows Command Prompt”或“Git from the command line and also from 3rd-party software”以确保git命令在PowerShell和VS Developer Command Prompt中都能直接使用。2.2 获取Carla源码与UE4引擎克隆Carla仓库 打开PowerShell建议以管理员身份运行避免后续创建符号链接时权限不足切换到一个有足够空间建议预留100GB以上的英文路径驱动器如D盘执行git clone https://github.com/carla-simulator/carla.git cd carla git checkout 0.9.15checkout命令确保我们切换到0.9.15这个特定版本的分支这是编译稳定性的关键。更新子模块 Carla依赖许多第三方库如LibCarla、RPCLib等它们作为子模块管理。这是第一个容易卡住的地方。由于网络问题直接git submodule update --init可能会失败。# 先尝试官方命令 git submodule update --init如果速度慢或失败可以修改.gitmodules文件中的URL将https://github.com/...替换为https://ghproxy.com/https://github.com/...使用代理加速或者使用--depth 1参数浅克隆。更稳妥的方法是进入Util目录使用项目提供的脚本cd Util python DownloadAssets.py这个脚本会下载预编译的依赖库可以跳过部分子模块的编译大大简化流程。获取Unreal Engine 4.26 这是整个编译过程中最特殊、也最容易出错的一环。UE4并非开源软件你需要注册Epic Games账户并关联你的GitHub账户从而获得访问UE4 GitHub仓库的权限。访问 Unreal Engine GitHub 按照指引关联账户。在本地使用Git克隆UE4.26分支。注意不要克隆到Carla目录内也不要放在有中文或空格的路径下。例如git clone -b 4.26 https://github.com/EpicGames/UnrealEngine.git D:\UE4.26UE4仓库巨大克隆需要很长时间且可能中断。如果中断可以进入目录执行git pull继续。克隆完成后进入D:\UE4.26目录找到Setup.bat右键“以管理员身份运行”。这个脚本会下载引擎所需的额外二进制组件如.NET框架、DirectX等并验证依赖。Setup.bat成功后运行GenerateProjectFiles.bat生成VS2019解决方案文件。最后用VS2019打开生成的UE4.sln在解决方案配置中选择“Development Editor”平台选择“Win64”然后进行编译。这个过程极其漫长视电脑性能可能需要2-6小时会占用大量CPU和内存。务必保持电脑供电稳定不要进行其他高负载操作。实操心得UE4的编译是对系统和耐心的巨大考验。我强烈建议在晚上睡觉前开始编译。另外确保系统虚拟内存设置足够大设置为物理内存的1.5-2倍并关闭所有不必要的软件特别是杀毒软件或将UE4和Carla目录添加到排除列表可以显著提高成功率并避免编译过程中文件被锁定的错误。3. 构建依赖与LibCarla编译基础环境就绪后我们进入核心的构建阶段。Carla的编译分为两部分一是构建所有C依赖库和核心通信库LibCarla二是在UE4编辑器中构建CarlaUE4项目即仿真世界本身。3.1 配置构建环境与编译LibCarla首先我们需要设置几个关键的环境变量让后续的构建脚本知道去哪里找Python和UE4。在Windows搜索栏输入“环境变量”打开“编辑系统环境变量”。在“系统变量”中新建或编辑以下变量PYTHONPATH: 指向你的Python安装目录例如D:\Python37。UE4_ROOT:至关重要指向你的UE4.26源码根目录例如D:\UE4.26。构建脚本会通过这个路径调用UE4的构建工具UnrealBuildTool。修改Path变量确保D:\Python37、D:\Python37\Scripts以及VS2019的MSBuild路径通常类似C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\MSBuild\Current\Bin位于其中。接下来打开“VS2019 Developer Command Prompt”不是普通的PowerShell或CMD。这个命令行环境已经配置好了VS的所有编译工具链。导航到你的Carla源码根目录。使用CMake生成构建文件 Carla使用CMake来管理跨平台的构建。在Carla根目录下通常会有一个CMakeLists.txt。但更推荐使用项目提供的Python构建脚本它封装了更复杂的逻辑。# 在Carla根目录下执行 make setupmake在这里不是Linux命令而是Carla项目根目录下的一个Python脚本make.py的快捷调用方式。make setup会执行一系列操作检查环境、下载部分依赖、配置CMake等。如果一切顺利你会看到大量输出信息。编译LibCarla LibCarla是Carla的C客户端库负责与仿真服务器通信。这是编译的主体部分之一。make build这个命令会启动LibCarla的编译。在Win11VS2019环境下你可能会遇到第一个典型的坑常见问题1boost库相关错误。错误信息可能包含“无法打开包括文件:boost/...”或“LNK1104: 无法打开文件libboost_...lib”。这是因为Carla依赖特定版本的Boost库如1.72.0或1.80.0而构建脚本尝试从源码编译Boost时可能失败。排查与解决检查Carla\Build目录下的日志文件。尝试手动安装Boost。从Boost官网下载对应版本的预编译二进制包如boost_1_72_0-msvc-14.2-64.exe其中msvc-14.2对应VS2019。安装时选择将库文件安装到C:\local\boost这样的路径。设置环境变量BOOST_ROOT指向Boost的安装根目录如C:\local\boost_1_72_0。清理构建缓存重新运行make build。有时需要手动删除Build文件夹下的内容。编译PythonAPI LibCarla编译成功后需要编译其Python绑定这样我们才能用Python脚本调用Carla。make PythonAPI这个步骤会为当前环境的Python3.7生成.egg或.whl文件。如果成功你会在PythonAPI\carla\dist目录下找到类似carla-0.9.15-py3.7-win-amd64.egg的文件。你可以使用pip install来安装这个文件到你的Python环境中。3.2 构建CarlaUE4项目Unreal Engine部分这是将Carla的仿真世界、蓝图、材质等资源打包进UE4编辑器项目的过程。生成UE4项目文件 在Carla根目录下运行make launch这个命令会做几件事调用UE4的UnrealBuildTool将Unreal\CarlaUE4目录下的资源编译成UE4编辑器可以打开的项目。第一次运行会非常慢因为它需要编译大量的Shader着色器和资源。注意make launch可能会在最后尝试自动打开UE4编辑器。如果它卡住或者失败没关系我们手动操作即可。关键看过程中有没有红色的错误Error信息只有警告Warning通常可以忽略。在UE4编辑器中打开并构建打开UE4.26的编辑器。通常可以通过编译好的UE4.sln解决方案以“Development Editor”模式启动或者直接运行D:\UE4.26\Engine\Binaries\Win64\UE4Editor.exe。在UE4编辑器中选择“打开项目”浏览到你的Carla源码目录下的Unreal\CarlaUE4文件夹选择CarlaUE4.uproject文件。UE4会提示“该项目是使用不同版本的引擎创建的需要重新构建”。点击“是”等待它重新编译模块。这个过程会编译Carla特有的UE4插件和模块。编译完成后编辑器正常打开。为了后续打包和运行方便我们还需要进行一步生成Visual Studio项目文件。在编辑器内点击菜单栏的文件 - 生成Visual Studio项目文件。这会在CarlaUE4目录下生成CarlaUE4.sln文件。打包项目可选但推荐 在编辑器内点击平台 - Windows - 打包项目选择输出目录如D:\CarlaPackaged。打包会将项目、引擎运行时和所有资源打包成一个独立的可执行文件.exe和若干数据文件。打包后的版本运行效率更高且不依赖完整的UE4编辑器环境便于分发和部署。但打包过程同样耗时很长1-3小时且需要大量磁盘空间。实操心得在Win11上UE4编辑器运行时可能会与系统图形驱动或某些后台服务如Xbox Game Bar冲突导致编辑器崩溃或无响应。如果遇到频繁崩溃可以尝试更新显卡驱动到最新稳定版在Windows设置中关闭“游戏模式”在任务管理器中禁用“Xbox Game Bar”相关服务。此外确保你的显卡支持DirectX 11/12这是UE4在Windows上的硬性要求。4. 环境验证与常见问题深度排查编译完成并不意味着万事大吉你需要验证整个环境是否真正可用。同时这里汇总了我在整个过程中遇到的最具代表性的“深坑”及其解决方案。4.1 验证安装与基础测试验证PythonAPI 在新的PowerShell窗口中激活你的Python 3.7环境安装之前编译好的PythonAPI。cd /d D:\carla\PythonAPI\carla\dist pip install carla-0.9.15-py3.7-win-amd64.egg然后运行一个简单的测试脚本检查是否能导入carla库并创建客户端。# test_carla.py import carla client carla.Client(localhost, 2000) client.set_timeout(10.0) print(client.get_available_maps())如果只是导入carla就报错可能是PythonAPI编译时链接的库与当前环境不匹配需要检查Python版本是否为严格的3.7。启动服务器并连接方法A使用打包版本导航到打包输出目录如D:\CarlaPackaged\WindowsNoEditor运行CarlaUE4.exe。这会启动Carla服务器并打开一个城镇场景窗口。方法B使用编辑器版本在UE4编辑器中打开CarlaUE4.uproject然后点击工具栏的“播放”按钮。或者在Carla源码根目录运行make launch如果配置正确它也会启动服务器。 服务器启动后默认监听端口2000。运行上面的Python测试脚本如果成功打印出地图列表如[Town01, Town02...]则说明客户端-服务器通信正常。运行示例脚本 Carla在PythonAPI\examples目录下提供了丰富的示例。运行一个简单的脚本如automatic_control.py可以综合测试传感器渲染、物理模拟、车辆控制等核心功能是否正常。cd /d D:\carla\PythonAPI\examples python automatic_control.py如果能看到车辆在城镇中自动行驶并且摄像头画面正常显示那么恭喜你整个Carla仿真环境已经成功搭建4.2 典型编译与运行问题实录问题1make build失败提示cl : Command line error D8021: invalid numeric argument /Wno-deprecated-register原因这个编译选项/Wno-deprecated-register是Clang的选项但MSVCVS的编译器不支持。Carla的某些依赖库如RPCLib的CMake文件可能没有为MSVC正确过滤此选项。解决找到报错的具体文件通常是某个第三方库的CMakeLists.txt。例如对于RPCLib可以编辑Build\rpclib-2.3.0\CMakeLists.txt找到包含-Wno-deprecated-register的行将其修改为针对MSVC的条件判断if(NOT MSVC) add_compile_options(-Wno-deprecated-register) endif()然后清除构建缓存删除Build文件夹下对应库的构建目录重新运行make build。问题2UE4编辑器编译CarlaUE4时报错“无法找到Carla.h等头文件”原因UE4的构建系统UnrealBuildTool没有正确找到LibCarla编译生成的头文件和库文件。make launch或项目构建脚本未能成功将LibCarla的输出目录链接到UE4项目的包含路径中。解决手动检查并设置。首先确认LibCarla已成功编译在carla\Build目录下应存在libcarla.lib等库文件和include文件夹。然后在UE4编辑器中打开CarlaUE4.uproject文件用文本编辑器确保其Modules部分正确引用了Carla模块。更直接的方法是在Carla源码根目录下运行make package或make rebuild这通常会重新建立正确的依赖关系。问题3运行Carla服务器打包版或编辑器时崩溃提示“VCRUNTIME140_1.dll 丢失”或类似DLL错误原因系统缺少Visual C Redistributable运行时库。虽然安装了VS2019但其运行时库可能未正确安装或注册。解决前往微软官网下载并安装“Microsoft Visual C Redistributable for Visual Studio 2015, 2017 and 2019”的x64版本。安装后重启电脑。这是运行任何用VS2019编译的应用程序的必备组件。问题4Python客户端能连接服务器但无法生成车辆或传感器返回错误信息原因可能的原因有多种。最常见的是服务器端的世界地图未正确加载或者客户端与服务器的版本不匹配尽管都是0.9.15但编译的Git提交哈希不同。排查检查服务器启动日志确认地图是否加载成功应看到“Loading mapTownXX...”等信息。在Python客户端中尝试world client.get_world()后打印world.get_map().name确认地图对象有效。确保Python客户端安装的carla包版本carla.__version__与服务器端编译的版本一致。最保险的做法是每次更新源码重新编译LibCarla后都重新安装一次PythonAPI\carla\dist下的egg文件。问题5性能问题编辑器或打包后游戏运行帧率FPS极低原因Carla对显卡要求较高且默认设置可能未优化。优化建议编辑器内在编辑器播放设置中降低渲染质量预设关闭抗锯齿、动态阴影等耗费资源的后期处理效果。打包版本创建或修改CarlaUE4\Saved\Config\WindowsNoEditor\Engine.ini在[/Script/Engine.RendererSettings]部分添加r.ScreenPercentage70将渲染分辨率降至70%可以大幅提升帧率。系统层面在NVIDIA控制面板针对N卡中将CarlaUE4.exe的电源管理模式设置为“最高性能优先”并确保使用的是独立显卡而非集成显卡。整个编译过程就像在组装一个精密的钟表任何一个齿轮的错位都会导致停摆。Win11的新特性、VS2019的特定版本、UE4.26的庞大生态三者交织在一起使得这个过程充满了挑战。但一旦你亲手将它搭建起来你对Carla内部结构的理解、对自动驾驶仿真系统依赖关系的把握都会达到一个全新的层次。这份实录里的每一个步骤和解决方案都源于实际踩坑后的复盘希望能成为你编译之路上的可靠地图。当你看到自己的车辆在亲手编译的仿真世界里飞驰时那种成就感绝对是直接下载二进制版本无法比拟的。