1. 环境准备搭建CARLA编译的基石第一次接触CARLA源码编译的朋友可能会被官方文档里列出的几十个依赖项吓到。别担心我去年在Ubuntu 20.04和Windows 10上都完整走通过这个流程这里把最关键的几个依赖整理给你。cmake和clang这两个工具链成员是必须的建议直接通过系统包管理器安装最新稳定版。我在AWS的t2.xlarge实例上测试时发现内存低于8GB很容易在编译UE4时崩溃所以本地机器配置不够的话可以考虑云服务。Python环境是另一个重灾区。CARLA官方推荐使用Python 3.7但实际测试发现3.8也能正常工作。关键是要用virtualenv创建独立环境避免和系统Python冲突。有次我偷懒直接用conda环境结果在编译PythonAPI时遇到诡异的链接错误浪费了半天时间排查。这里分享我的标准操作sudo apt-get install cmake clang-10 libomp-dev python3.7 -m venv carla-env source carla-env/bin/activateWindows用户需要特别注意Visual Studio 2019的C桌面开发组件必须勾选而且安装路径不要有中文或空格。我见过最离奇的编译失败案例就是因为用户把VS装在D:\编程工具目录下CMake死活找不到编译器。2. 获取UE4引擎权限陷阱与分支选择官方文档说要用git clone --depth 1 -b carla https://github.com/CarlaUnreal/UnrealEngine.git获取特定分支但新手最容易栽在第一步——Epic Games账号绑定。你必须先在Epic官网关联GitHub账号然后去邮箱确认加入Epic组织否则clone时会提示403 forbidden。这个步骤没有任何错误提示我第一次遇到时还以为是代理问题折腾了两小时才反应过来。引擎版本匹配也是个暗坑。CARLA 0.9.14对应UE4.26但最新master分支可能要求UE4.27。有次我图省事直接拉最新UE结果编译到80%报出一堆材质错误。后来在CARLA的ContentVersions.txt里找到对应版本号才解决。建议clone前先查清楚版本对应关系不然十几个小时的编译时间就打水漂了。下载后的引擎源码建议放在SSD上机械硬盘的编译速度能慢上3-5倍。我在老笔记本上测试时完整编译UE4需要近6小时换成NVMe SSD后缩短到2小时。如果中途遇到Unexpected end of file错误大概率是磁盘IO瓶颈导致的。3. 地图资源下载失效链接的应对方案编译过程中最让人崩溃的莫过于地图包下载失败。官方Update.bat脚本里的S3链接早就失效了新地址迁移到了Backblaze存储。这里分享我的手动下载方案打开UnrealEngine/carla/Util/ContentVersions.txt查看当前版本号拼接下载链接https://carla-assets.s3.us-east-005.backblazeb2.com/[版本号].tar.gz用aria2多线程下载aria2c -x16 -s16 [链接]比如0.9.14版本的命令应该是aria2c -x16 -s16 https://carla-assets.s3.us-east-005.backblazeb2.com/20221201_5ec9328.tar.gz下载完成后要手动解压到UnrealEngine/carla/Unreal/CarlaUE4/Content目录。有次我犯懒直接用图形界面解压结果路径多了一层导致引擎找不到资产。正确的目录结构应该是Content/Maps/*.umap而不是Content/carla-assets/Maps/*.umap。4. PythonAPI编译多环境引发的灾难PythonAPI编译失败十有八九是环境问题。最常见的是bdist_wheel报错根本原因是系统存在多个Python解释器。我建议直接修改BuildPythonAPI.bat第112行原命令py -3 setup.py bdist_egg bdist_wheel修改为python setup.py bdist_egg bdist_wheel更隐蔽的坑是protobuf版本冲突。CARLA要求protobuf3.19.0但有些机器学习框架会自动安装新版。有次我的环境里同时存在3.19.0和4.21.1两个版本导致生成的Python绑定无法被C识别。解决方案是在virtualenv里先卸载所有protobuf再重新安装指定版本pip uninstall protobuf pip install protobuf3.19.05. 网络问题终极解决方案osm2odr编译失败十次有九次是网络问题。常规的git clone会因为各种原因卡住我的解决方案是分步操作删除可能存在的半成品rm -rf osm2odr-visualstudio libcarla-visualstudio使用镜像源加速git config --global url.https://ghproxy.com/https://github.com.insteadOf https://github.com开启IPv4优先某些云服务器需要echo precedence ::ffff:0:0/96 100 | sudo tee -a /etc/gai.conf对于必须从国外下载的依赖建议用wget的--retry参数自动重试。我在阿里云上测试时这个配置成功下载了原本会超时的文件wget --tries10 --retry-connrefused --retry-on-http-error503 https://example.com/file.zip6. 编译后的验证与调试看到Build successful提示先别急着庆祝我建议立即运行两个测试启动CarlaUE4编辑器./CarlaUE4.sh -opengl如果报错找不到libomp需要设置环境变量export LD_LIBRARY_PATH/usr/lib/llvm-10/lib:$LD_LIBRARY_PATH运行Python示例import carla client carla.Client(localhost, 2000) print(client.get_available_maps())常见问题排查如果Python报错ImportError: libcarla.so not found需要把PythonAPI/carla/dist/加入LD_LIBRARY_PATH编辑器闪退可能是显卡驱动问题试试加上-vulkan或-dx11参数地图加载缓慢可以编辑CarlaUE4/Config/DefaultGame.ini调整流式加载参数最后提醒一个小细节编译生成的Python包路径在PythonAPI/carla/dist/下但pip安装时要用绝对路径。我习惯建立软链接避免每次都要重新安装pip install -e /path/to/carla/PythonAPI/carla/dist/carla-0.9.14-py3.7-linux-x86_64.egg
CARLA源码编译实战：从零到一的环境搭建与疑难解析
发布时间：2026/5/19 6:51:36
1. 环境准备搭建CARLA编译的基石第一次接触CARLA源码编译的朋友可能会被官方文档里列出的几十个依赖项吓到。别担心我去年在Ubuntu 20.04和Windows 10上都完整走通过这个流程这里把最关键的几个依赖整理给你。cmake和clang这两个工具链成员是必须的建议直接通过系统包管理器安装最新稳定版。我在AWS的t2.xlarge实例上测试时发现内存低于8GB很容易在编译UE4时崩溃所以本地机器配置不够的话可以考虑云服务。Python环境是另一个重灾区。CARLA官方推荐使用Python 3.7但实际测试发现3.8也能正常工作。关键是要用virtualenv创建独立环境避免和系统Python冲突。有次我偷懒直接用conda环境结果在编译PythonAPI时遇到诡异的链接错误浪费了半天时间排查。这里分享我的标准操作sudo apt-get install cmake clang-10 libomp-dev python3.7 -m venv carla-env source carla-env/bin/activateWindows用户需要特别注意Visual Studio 2019的C桌面开发组件必须勾选而且安装路径不要有中文或空格。我见过最离奇的编译失败案例就是因为用户把VS装在D:\编程工具目录下CMake死活找不到编译器。2. 获取UE4引擎权限陷阱与分支选择官方文档说要用git clone --depth 1 -b carla https://github.com/CarlaUnreal/UnrealEngine.git获取特定分支但新手最容易栽在第一步——Epic Games账号绑定。你必须先在Epic官网关联GitHub账号然后去邮箱确认加入Epic组织否则clone时会提示403 forbidden。这个步骤没有任何错误提示我第一次遇到时还以为是代理问题折腾了两小时才反应过来。引擎版本匹配也是个暗坑。CARLA 0.9.14对应UE4.26但最新master分支可能要求UE4.27。有次我图省事直接拉最新UE结果编译到80%报出一堆材质错误。后来在CARLA的ContentVersions.txt里找到对应版本号才解决。建议clone前先查清楚版本对应关系不然十几个小时的编译时间就打水漂了。下载后的引擎源码建议放在SSD上机械硬盘的编译速度能慢上3-5倍。我在老笔记本上测试时完整编译UE4需要近6小时换成NVMe SSD后缩短到2小时。如果中途遇到Unexpected end of file错误大概率是磁盘IO瓶颈导致的。3. 地图资源下载失效链接的应对方案编译过程中最让人崩溃的莫过于地图包下载失败。官方Update.bat脚本里的S3链接早就失效了新地址迁移到了Backblaze存储。这里分享我的手动下载方案打开UnrealEngine/carla/Util/ContentVersions.txt查看当前版本号拼接下载链接https://carla-assets.s3.us-east-005.backblazeb2.com/[版本号].tar.gz用aria2多线程下载aria2c -x16 -s16 [链接]比如0.9.14版本的命令应该是aria2c -x16 -s16 https://carla-assets.s3.us-east-005.backblazeb2.com/20221201_5ec9328.tar.gz下载完成后要手动解压到UnrealEngine/carla/Unreal/CarlaUE4/Content目录。有次我犯懒直接用图形界面解压结果路径多了一层导致引擎找不到资产。正确的目录结构应该是Content/Maps/*.umap而不是Content/carla-assets/Maps/*.umap。4. PythonAPI编译多环境引发的灾难PythonAPI编译失败十有八九是环境问题。最常见的是bdist_wheel报错根本原因是系统存在多个Python解释器。我建议直接修改BuildPythonAPI.bat第112行原命令py -3 setup.py bdist_egg bdist_wheel修改为python setup.py bdist_egg bdist_wheel更隐蔽的坑是protobuf版本冲突。CARLA要求protobuf3.19.0但有些机器学习框架会自动安装新版。有次我的环境里同时存在3.19.0和4.21.1两个版本导致生成的Python绑定无法被C识别。解决方案是在virtualenv里先卸载所有protobuf再重新安装指定版本pip uninstall protobuf pip install protobuf3.19.05. 网络问题终极解决方案osm2odr编译失败十次有九次是网络问题。常规的git clone会因为各种原因卡住我的解决方案是分步操作删除可能存在的半成品rm -rf osm2odr-visualstudio libcarla-visualstudio使用镜像源加速git config --global url.https://ghproxy.com/https://github.com.insteadOf https://github.com开启IPv4优先某些云服务器需要echo precedence ::ffff:0:0/96 100 | sudo tee -a /etc/gai.conf对于必须从国外下载的依赖建议用wget的--retry参数自动重试。我在阿里云上测试时这个配置成功下载了原本会超时的文件wget --tries10 --retry-connrefused --retry-on-http-error503 https://example.com/file.zip6. 编译后的验证与调试看到Build successful提示先别急着庆祝我建议立即运行两个测试启动CarlaUE4编辑器./CarlaUE4.sh -opengl如果报错找不到libomp需要设置环境变量export LD_LIBRARY_PATH/usr/lib/llvm-10/lib:$LD_LIBRARY_PATH运行Python示例import carla client carla.Client(localhost, 2000) print(client.get_available_maps())常见问题排查如果Python报错ImportError: libcarla.so not found需要把PythonAPI/carla/dist/加入LD_LIBRARY_PATH编辑器闪退可能是显卡驱动问题试试加上-vulkan或-dx11参数地图加载缓慢可以编辑CarlaUE4/Config/DefaultGame.ini调整流式加载参数最后提醒一个小细节编译生成的Python包路径在PythonAPI/carla/dist/下但pip安装时要用绝对路径。我习惯建立软链接避免每次都要重新安装pip install -e /path/to/carla/PythonAPI/carla/dist/carla-0.9.14-py3.7-linux-x86_64.egg
