1. 为什么选择SUMO，它能解决什么问题
做交通仿真这块的人，几乎都绕不开SUMO。全称Simulation of Urban Mobility，是一个开源、微观、空间连续的交通仿真平台，由德国航空航天中心主导开发，从2001年发展到现在，已经成了学术界和工业界用得最广泛的交通仿真工具之一。我最早接触SUMO是在做车路协同项目的时候，当时需要在仿真环境里测试V2X通信对交叉口通行效率的影响，商业软件要么授权贵得离谱，要么没法做二次开发，SUMO几乎是唯一能把路网建模、车辆行为、交通信号控制、通信接口全部打通的开源方案。
这篇内容适合谁？如果你是刚接触交通仿真的大学生、刚入行的交通工程师、做自动驾驶仿真测试的算法工程师，或者想在论文里加一个仿真验证章节的研究者，这篇内容可以帮你把SUMO的基础脉络一次性理清。文章不会堆砌官方文档的翻译，而是按照“为什么选它—怎么装—核心概念怎么理解—怎么从零搭一个能跑的仿真—遇到坑怎么排查”这条真实的学习路径来写。
SUMO本身的价值可以概括成三句话：第一，微观层面，每一辆车都有独立的跟驰模型、换道模型和路径选择逻辑，能模拟出真实的交通流特征；第二，开放层面，所有核心功能都有Python/C++接口，TraCI接口可以实时读取和修改仿真状态，这意味着你可以拿它做强化学习环境、做硬件在环、做数字孪生；第三，生态层面，自带sumo-gui可视化、netedit路网编辑器、活动基生成工具，配合第三方库如sumolib、traci，基本可以覆盖从路网建模到结果分析的全链路。
我见过不少人一上来就下载安装，然后被一堆XML文件劝退。其实SUMO的学习曲线陡，不是陡在软件本身，而是陡在你对“路网—需求—仿真—分析”这条链路没有一个整体认知。这篇文章就是帮你把这条链路走通一遍。
2. 环境准备与安装要点
2.1 Windows/Linux/macOS安装差异
SUMO的安装方式不复杂，但不同系统有不同讲究。Windows用户最省事的方式是去官网下载安装包，注意安装路径里不要有中文和空格，否则后续调用命令行工具时经常出一些莫名其妙的路径解析问题。安装完成后，把SUMO的bin目录加到系统环境变量PATH里，这样可以在任意目录直接运行sumo、netedit、python tools等命令。
Linux用户建议用apt或源码编译。Ubuntu/Debian直接sudo apt install sumo sumo-tools sumo-doc就行了，这套包会装好可执行文件、Python工具脚本和文档。但如果你的项目需要改动SUMO源码，或者需要和特定版本的TraCI接口匹配，那就必须走源码编译。源码编译有几个前置依赖：cmake、g++、libxerces-c-dev、libfox-1.6-dev、libgl1-mesa-dev、libproj-dev。编译步骤很标准：
git clone --recursive https://github.com/eclipse-sumo/sumo.git cd sumo mkdir build && cd build cmake .. make -j$(nproc)macOS用户用Homebrew装最省心：brew install sumo。装完同样要确认PATH里能找到sumo命令。
2.2 验证安装是否成功
装完之后验证一下环境是否正常。打开终端，运行：
sumo --version正常情况下会输出类似SUMO Version 1.18.0这样的信息。再跑一下netedit --version确认路网编辑器可用。如果这两个命令都能正常执行，说明基础环境没问题。
还有一个很容易被忽略的验证点，就是Python工具脚本能否正常调用。SUMO的tools目录下有几百个Python脚本，是官方提供的辅助工具。建议测试一下：
python3 -c "import traci; print(traci.__name__)" python3 -c "import sumolib; print(sumolib.__name__)"如果提示找不到模块，大概率是没把tools目录加入PYTHONPATH。Windows下可以在系统环境变量里加一个PYTHONPATH指向安装目录下的tools文件夹。这一步很多人不注意，等到写TraCI脚本的时候才回头补。
2.3 版本选择建议
SUMO迭代速度挺快的，基本每年发布2个版本。2024年后比较稳定的版本是1.18和1.20，我建议新用户直接用官方最新稳定版。有些老教程是基于0.32这种远古版本写的，里面的XML格式和参数已经变了，照着抄会报错。比如早期的<lane>元素里没有allow和disallow属性，信号灯逻辑的写法也和现在差异很大。所以遇到问题先看官方文档里对应版本的changelog，别硬套老教程。
3. SUMO核心概念拆解
3.1 路网文件：不是一张图，是一堆XML
SUMO的路网文件后缀是.net.xml，很多人第一次打开会被里面密密麻麻的XML标签吓到。其实理解了它的结构，就理解了SUMO路网的本质：一个有向图。节点（node）是交叉口或道路端点，边（edge）是路段，每条边包含若干条车道（lane），车道之间有连接关系（connection）。这和我们平时用matplotlib画个示意图完全不同，SUMO的路网是带拓扑信息和几何信息的结构化数据。
一个最简单路网的.net.xml大致长这样：
<net version="1.18" xml:lang="en"> <edge id="e0" from="n0" to="n1"> <lane id="e0_0" index="0" speed="13.89" length="200.00"/> </edge> </net>注意两点。第一，edge的id和lane的id是两级命名，lane id是edgeId_index的格式，很多脚本处理时都是从lane id里split出edge id。第二，speed单位是m/s，不是km/h。13.89对应50km/h，这是新手最容易算错的地方。我见过不少人在构建路网时把限速填成50，结果所有车都堵在入口处，以为是模型问题，其实是速度单位搞错了。
3.2 需求文件：车从哪里来，到哪里去
路网只是舞台，还得有演员。SUMO的出行需求要靠.rou.xml文件定义，里面包含两类核心元素：车辆类型（vType）和车辆流（flow）或单辆车（vehicle）。
vType是定义车辆行为的核心，包括车辆长度、最大速度、加速度、跟驰模型参数等。一个典型的小客车vType：
<vType id="car" vClass="passenger" accel="2.6" decel="4.5" sigma="0.5" length="4.5" minGap="2.5" maxSpeed="16.67"/>这里的accel、decel是最大加速度和最大减速度，sigma是驾驶员的随机性参数，sigma越大驾驶行为越激进越随机，minGap是车辆完全停住时与前车的间距。这些参数直接决定仿真结果，不能随便填。
生成车流有两种方式。流量小的时候可以直接定义单辆车，指定depart时间：
<vehicle id="v1" type="car" depart="0.00" route="r0"/>流量大的时候用flow批量生成：
<flow id="f1" type="car" from="e0" to="e2" begin="0" end="3600" period="5" />这里的period是发车时间间隔，period=5表示每5秒发一辆车，等效流量是720辆/小时。注意flow和vehicle不能混用同一个id前缀，否则会报警告。
3.3 路由文件：车怎么走
SUMO里车辆必须绑定路线（route）。最简单的路线就是一条edge序列：
<route id="r0" edges="e0 e1 e2"/>它的含义是车辆从e0出发，依次经过e1、e2。如果不在rou.xml里指定route，就需要有路由计算模块介入。常见的做法是用duarouter工具或sumolib的route计算功能。实际项目中，如果路网比较复杂，手动维护route列表非常痛苦，一般会选择在仿真运行时用TraCI动态分配路线，或者用flow配合from和to属性让SUMO自己算最短路径。
3.4 配置文件：把所有东西串起来
最后需要一个.sumocfg文件，它是整个仿真的启动入口，把路网、需求、输出文件全部串起来：
<?xml version="1.0" encoding="UTF-8"?> <configuration> <input> <net-file value="network.net.xml"/> <route-files value="routes.rou.xml"/> </input> <time> <begin value="0"/> <end value="3600"/> </time> <output> <tripinfo-output value="tripinfo.xml"/> <summary-output value="summary.xml"/> </output> </configuration>配置文件的本质就是命令行参数的XML化。你在命令行里写sumo -n network.net.xml -r routes.rou.xml --end 3600，和写配置文件的效果完全一样。用配置文件的好处是可以把不同场景的参数固化下来，方便实验管理。
4. 从零构建一个完整仿真案例
4.1 方案设计：一个十字交叉口的潮汐交通
这里用一个典型的十字交叉口案例作为教程主线。场景设定：南北向和东西向道路交叉，每条道路双向两车道，限速50km/h。东西向为主干道，早高峰流量大，南北向为支路，流量较小。仿真时长1小时，需要统计交叉口的平均延误和排队长度。
之所以选这个案例，是因为它覆盖了SUMO入门必需的全部基本操作：用netedit画路网、定义交通信号灯、生成OD需求、运行仿真、分析输出文件。这个流程一旦走通，后面做区域路网、高速合流区、公交优先等场景都只是在这个框架上做替换。
4.2 用netedit绘制路网
启动netedit：
netedit -s-s参数表示新建一个路网而不是打开已有文件。界面操作流程如下：
- 在Network模式下，用鼠标在画布上点击创建节点。先画5个节点，构成一个十字：中心节点是交叉口，上下左右四个方向各有一个端点节点。
- 切换到Edge模式，依次点击两个节点创建路段。注意SUMO里edge是单向的，双向道路需要分别创建两条方向相反的edge。
- 选中每条edge，在右侧属性栏中设置车道数、限速。本例中所有道路都设为2条车道、限速13.89m/s。
- 保存路网文件为
cross.net.xml。
实际画的时候有几个细节容易出错。第一，节点之间必须有足够的距离，至少要大于一个车身长度加安全间距，否则车辆刚生成就撞上前车。第二，交叉口处默认会生成转向连接，但如果你的交叉口有禁左或者禁右需求，需要手动在连接模式下删除特定的connection。第三，限速设置时要注意单位，netedit里可以直接用km/h，但导出的net.xml里一定是m/s。
画完路网后，建议用netconvert --validate验证一下路网拓扑是否完整。如果网络有断头路、孤立节点，工具会给出警告。
4.3 编写需求文件
在工程目录下新建cross.rou.xml，填入以下内容：
<?xml version="1.0" encoding="UTF-8"?> <routes> <vType id="car" accel="2.6" decel="4.5" sigma="0.5" length="4.5" minGap="2.5" maxSpeed="13.89"/> <route id="WE" edges="e0 e2"/> <route id="EW" edges="e3 e1"/> <route id="NS" edges="e4 e6"/> <route id="SN" edges="e7 e5"/> <flow id="we_flow" type="car" route="WE" begin="0" end="3600" period="3"/> <flow id="ew_flow" type="car" route="EW" begin="0" end="3600" period="3"/> <flow id="ns_flow" type="car" route="NS" begin="0" end="3600" period="8"/> <flow id="sn_flow" type="car" route="SN" begin="0" end="3600" period="8"/> </routes>这段配置的含义是：东西向主干道每3秒发一辆车，等效流量1200辆/小时；南北向支路每8秒发一辆车，等效流量450辆/小时。早上8点早高峰时段，东西向的流量压力明显更大。
关于edge id，netedit默认生成的id可能是随机的，也可能是我这里写的e0/e1这种递增模式。如果你在netedit里建路时没有修改id，一定要先打开保存的cross.net.xml确认一下实际的edge id，然后照着真实的id修改routes文件。这个步骤别跳，不然后面运行仿真时会报“route uses unknown edge”错误。
4.4 配置信号灯
信号灯是交叉口仿真里最核心的控制逻辑。在netedit里选中交叉口中心节点，在属性栏里点击“Traffic Light”按钮，SUMO会为该节点生成一套默认的信号方案。默认方案通常是一个两相位方案，即南北绿灯+东西红灯，然后切换。
但真实场景中，东西向主干道流量大，应该分配更长的绿灯时长。我们需要打开cross.net.xml，找到信号灯控制器的定义，修改相位时长。信号灯的XML结构通常在<tlLogic>标签里：
<tlLogic id="n1" type="static" programID="0" offset="0"> <phase duration="30" state="GGggrrrr"/> <phase duration="5" state="yyggrrrr"/> <phase duration="30" state="rrrrGGgg"/> <phase duration="5" state="rrrryygg"/> </tlLogic>state字符串里的每个字符代表一个信号灯组。大写G是绿色，大写y是黄色，大写r是红色。字符串是按固定的顺序排列的，映射到该节点连接的每一条车道对应的信号灯。改的时候注意，state的排列顺序要和交叉口的connections顺序一致。
我的设计是：东西向绿灯30秒，黄灯5秒，南北向绿灯30秒，黄灯5秒。这样四个方向的一个完整信号周期是70秒，东西向的有效绿信比略高。
4.5 运行仿真与可视化
执行：
sumo -c cross.sumocfg如果一切正常，终端会滚动输出仿真日志，并在结束后生成tripinfo.xml和summary.xml两个输出文件。
加上GUI可视化就运行：
sumo-gui -c cross.sumocfg打开后按Ctrl+D进入仿真模式，或者直接在控制栏点“运行”按钮。速度调成10倍速观察，你会看到车辆在接近交叉口时减速排队，绿灯亮起后依次通过。如果车辆在停车线前随机消失，大概率是信号灯相位和连接关系不匹配，车辆找不到通过的路径，自行蒸发。这个问题我们后面再细说。
4.6 用TraCI做动态干预
静态仿真跑通之后，SUMO真正的威力才刚开始——TraCI接口。TraCI允许外部程序在仿真运行时通过TCP连接实时读取和修改仿真状态。做信号灯自适应控制、车辆轨迹干预、动态路径诱导，都依赖这个接口。
一个最简单的TraCI Python脚本，每隔5秒调整一次信号灯相位：
import traci import sumolib sumoBinary = "sumo-gui" sumoCmd = [sumoBinary, "-c", "cross.sumocfg", "--start"] traci.start(sumoCmd) step = 0 while step < 3600: traci.simulationStep() if step % 5 == 0: # 读取当前排队长度 waiting = traci.lane.getWaitingTime("e0_0") print(f"Step {step}, lane e0_0 waiting time: {waiting:.2f}") step += 1 traci.close()需要注意：TraCI脚本一定要在step循环里调用traci.simulationStep()，这个函数每调用一次，仿真前进一个时间步长（默认1秒）。忘记调用这个函数是新手最常见的错误，结果是仿真卡死在第一步，GUI界面毫无反应。
5. 常见问题与排查技巧
5.1 车辆在路网中神秘消失
现象：车辆跑着跑着，在某个节点附近突然不见了，但仿真没有报错。原因通常是路网拓扑不完整，车辆到达一个没有出口连接的车道，SUMO判定该车无法继续行驶，就把它从仿真中移除。
排查方法：打开--pedestrian-model之类的额外输出没有用，大概率问题出在net文件内部。用sumo-gui打开路网，放大到消失点附近检查是否存在断头车道。更暴力但高效的方式是执行：
netconvert -s cross.net.xml --geometry.remove --plain-output-prefix plain这会生成plain格式的路网文件，用文本编辑器检查每条edge的<connection>定义，看看是否有缺失的转向连接。
经验之谈：新手画路网时，经常忘记在交叉口处为右转车道配置连接。SUMO默认情况下，如果某个转向没有明确连接定义，该方向车辆就会被“蒸发”。处理方法是在netedit的连接模式下，手动补全转向连接。
5.2 信号灯相位和实际车流方向不匹配
现象：绿灯亮了，但某条车道上的车不动；红灯亮了，车反而在走。这是state字符串和连接顺序不匹配导致的。
排查方法：在sumo-gui里右键点击信号灯节点，选择“Show Phases”，逐相位查看信号灯组的状态。同时打开“Show connections”模式，对比每个信号灯组对应的是哪条车道。注意SUMO对state字符串的解析规则是区分大小写的：小写字母表示对应方向的信号灯不激活，比如g表示该信号灯在绿灯但不允许行人通过，y表示黄灯闪烁。别小看大小写，一个字符错了整个信号方案就乱了。
5.3 车辆堵在出口不动
现象：车流在交叉口内部形成死锁，车辆全部停在交叉口内部，谁也无法移动。这通常是典型的“网格锁死”。当路口四个方向的车流都拥堵到交叉口内部，后续车辆又不断进入，整个交叉口就被车流填满了。
排查方法：减少入流量（增大period），或者引入“gap”策略。SUMO里有个参数--ignore-junction-blocker，但更合理的做法是从需求端减少流量，或者在交叉口入口处加装“出口限制”逻辑，保证车辆只有在出口方向空间充足时才进入路口。
经验之谈：模拟真实路口的死锁情况本身是研究课题，但如果你的目标是验证信号控制方案，网格锁死往往说明流量设置超出了道路容量。先算一下理论容量：单车道饱和流量约1800辆/小时，双车道接近3600辆/小时。如果四个方向总到达流量超过交叉口总通行能力，锁死几乎必然发生。
5.4 Python报错“connection refused”
现象：TraCI脚本运行时报“could not connect to port 8873”之类的错误。
排查方法：先检查sumo是否真的启动成功了。在命令行模式（不加-gui）下运行：
sumo -c cross.sumocfg --remote-port 8873然后脚本连接localhost:8873。很多情况下报错是因为在同一个进程里重复调用了traci.start()，或者多个脚本抢同一个端口。解决方法是在项目中固定一个端口号，并且确保调用traci.close()释放连接。
5.5 仿真结果数值不合理的排查思路
如果仿真跑完了，但统计出来的平均车速异常低、平均延误异常高，先别急着怀疑模型，按这个顺序排查：第一步，查看路网限速设置是否合理；第二步，检查需求文件中的流量是否超过了通行能力；第三步，检查信号灯绿灯时间是否短于一个周期内的累计到达车流所需通过时间；第四步，把sumo-gui的车辆着色方式改成“速度”，一目了然地看哪些路段持续拥堵，定位瓶颈路段。
还有一个经常被忽略的输出参数：--statistic-output，它会输出一个详细的统计文件，包含每段道路的流量、平均速度、平均密度。用这个文件做数据对比，比直接盯着GUI判断要客观得多。
6. 进阶扩展的方向
一个十字路口仿真跑通之后，可以根据自己的研究或项目方向做扩展。比如加入公交线路，在netedit里为公交车设置专用道路和停靠站，在rou.xml里定义vType="bus"的车辆，用stop元素指定公交车停靠的位置和时长。公交车的加减速特性和乘客上下车delay很好模拟，适合做公交优先信号控制研究。
另一个常见扩展是做多路口协调控制。把一个十字路口的路网替换成一条主干道上的5个连续交叉口，信号方案用线性协调，也就是绿波控制。SUMO支持信号灯之间的offset参数设置，可以通过调整offset实现车辆在连续交叉口不停车通过。我做过一次绿波实验，在离线场景下把干道平均行程时间缩短了约20%，效果非常明显。
再进阶一点就是强化学习信号控制。用TraCI作为环境接口，把每个路口的相位和绿灯时间作为动作空间，排队长度作为状态，平均延误作为奖励函数，用任意强化学习框架去训练一个控制策略。SUMO和RL结合的案例在GitHub上有不少开源项目，搜索“SUMO RL traffic signal”能找到参考。
还有一条路线是做微观轨迹级的分析。SUMO默认的FCD输出（Floating Car Data）可以记录每辆车每个时间步的位置、速度、加速度，导出的XML数据可以转成csv，用Python做轨迹分析或者可视化。这在自动驾驶仿真里用得很多，V2X算法测试时，真实车辆轨迹往往拿不到，SUMO生成的轨迹就是模拟替代方案。
7. 我的一些实用体会
最后分享几个实用的体会。
第一，学习SUMO不要一开始就读官方文档的英文原始文档。文档没毛病，但信息密度太高，容易迷失。学习路径应该是：先跑通一个最简单案例，然后遇到具体需求再定向去查文档。比如需要搞懂tripinfo.xml各个字段的含义时，再去搜文档里对应的章节，效果比从头读官方文档好十倍。
第二，正式仿真前一定要先跑一小段时间做快速验证。比如先把end时间设为60秒，用GUI模式跑一下，看看车辆行为是否符合预期，再改成3600秒的完整仿真。否则一旦跑完1小时仿真发现路网画错了，重跑的时间成本就很高了。
第三，所有数据文件建议都放在同一个工程目录下，用相对路径引用。我在项目里见过太多人用绝对路径写了某个配置文件，换一台电脑后所有路径全部失效。相对路径是自包含的，配合Git做版本管理也方便。
第四，SUMO自带的tools目录是宝藏。除了traci和sumolib，还有tools/route下的随机路线生成器、tools/output下的结果分析工具、tools/net下的路网转换工具。做项目之前先花半小时翻一遍tools目录，你会发现自己要造的轮子官方基本都有。
第五，遇到报错别慌。SUMO的报错信息虽然看起来晦涩，但基本都能在官方文档的FAQ页面找到对应解释。把报错信息完整复制到搜索引擎里，十有八九能搜到前人踩过的同一个坑。
SUMO是一个上限极高的工具，从最基础的交叉口仿真到大规模城市路网、从静态信号控制到强化学习信号优化、从微观车辆轨迹到交通需求预测，整个生态链条非常完整。这篇文章帮你打通了从安装到跑通第一个仿真案例的完整链路，剩下的就靠你在实际项目里继续积累了。
