Windows系统Python调用SUMO TraCI接口全流程指南

第一次接触SUMO交通仿真系统时，最令人头疼的莫过于环境配置问题。明明按照官方文档一步步操作，却总是遇到各种报错，尤其是Python调用TraCI接口时出现的"ModuleNotFoundError"或"SUMO_HOME not declared"错误，让不少初学者望而却步。本文将带你从零开始，避开所有常见陷阱，在Windows系统上完美配置Python与SUMO的交互环境。

1. 环境准备：安装SUMO与Python

在开始之前，我们需要确保系统中已安装正确版本的SUMO和Python。以下是详细的安装步骤和版本选择建议：

1.1 下载与安装SUMO

SUMO官方提供了Windows平台的安装包，建议从官网下载最新稳定版本：

1. 访问 SUMO官网下载页面
2. 选择与系统匹配的安装包（通常为64位版本）
3. 运行安装程序， 记住安装路径 （默认路径为 C:\Program Files (x86)\Eclipse\Sumo ）

注意：安装路径中不要包含中文或特殊字符，这可能导致后续配置出现问题。

1.2 Python环境配置

SUMO TraCI接口支持Python 3.6及以上版本。推荐使用Anaconda管理Python环境：

conda create -n sumo python=3.8
conda activate sumo

如果使用原生Python，确保已将其添加到系统环境变量PATH中。可以通过命令提示符验证：

python --version

2. 关键配置：环境变量与路径设置

环境变量配置是SUMO与Python交互的核心环节，也是最容易出错的部分。我们将详细解析每个配置项的作用和正确设置方法。

2.1 设置SUMO_HOME环境变量

SUMO_HOME 是SUMO运行必需的环境变量，指向SUMO的安装目录：

1. 右键"此电脑" → 属性 → 高级系统设置 → 环境变量
2. 在"系统变量"中点击"新建"
3. 变量名输入 SUMO_HOME
4. 变量值为SUMO安装路径（如 C:\Program Files (x86)\Eclipse\Sumo ）

验证设置是否成功：

echo %SUMO_HOME%

2.2 配置Python路径

SUMO的TraCI接口需要通过 .pth 文件告知Python其位置：

1. 找到Python的 site-packages 目录（通常在 Python安装目录\Lib\site-packages ）
2. 新建文本文件，重命名为 traci.pth
3. 编辑文件内容，写入SUMO中TraCI工具的路径（如 C:\Program Files (x86)\Eclipse\Sumo\tools ）

注意：文件扩展名必须是 .pth 而非 .pth.txt ，确保Windows显示文件扩展名后再重命名。

3. 常见问题排查与解决方案

即使按照步骤操作，仍可能遇到各种问题。以下是几个典型错误及其解决方法：

3.1 "ModuleNotFoundError: No module named 'traci'"

这个错误通常由以下原因导致：

• .pth 文件位置错误：确保文件在正确的 site-packages 目录
• .pth 文件内容错误：路径应指向SUMO的 tools 目录
• Python环境未激活：如果使用conda，确保已激活正确环境

3.2 "please declare environment variable 'SUMO_HOME'"

这表明Python无法识别SUMO的安装位置：

• 检查 SUMO_HOME 是否设置正确
• 确保在运行Python前已设置环境变量（可能需要重启终端或IDE）
• 尝试在Python代码中临时设置：

import os
os.environ['SUMO_HOME'] = 'C:\\Program Files (x86)\\Eclipse\\Sumo'

3.3 路径中的空格问题

SUMO默认安装在 Program Files (x86) 目录，路径中的空格可能导致问题。解决方法有：

1. 安装SUMO时选择无空格的路径（如 C:\SUMO ）
2. 在Python代码中使用原始字符串或双反斜杠：

os.environ['SUMO_HOME'] = r'C:\Program Files (x86)\Eclipse\Sumo'
# 或
os.environ['SUMO_HOME'] = 'C:\\Program Files (x86)\\Eclipse\\Sumo'

4. 第一个TraCI脚本：车辆仿真示例

配置完成后，让我们编写一个简单的TraCI脚本，模拟车辆在路网中的运行：

from __future__ import absolute_import
import os
import sys
import traci
from sumolib import checkBinary

# 确保SUMO_HOME已设置
if 'SUMO_HOME' in os.environ:
    tools = os.path.join(os.environ['SUMO_HOME'], 'tools')
    sys.path.append(tools)
else:
    sys.exit("请设置SUMO_HOME环境变量")

# 启动SUMO-GUI
sumoBinary = checkBinary('sumo-gui')
sumoCmd = [sumoBinary, "-c", "your_config.sumocfg"]

traci.start(sumoCmd)

# 仿真循环
for step in range(100):
    traci.simulationStep()
    vehicle_ids = traci.vehicle.getIDList()
    for vid in vehicle_ids:
        position = traci.vehicle.getPosition(vid)
        print(f"车辆{vid}位置: {position}")

traci.close()

4.1 代码解析

1. checkBinary ：自动检测系统中可用的SUMO二进制文件（sumo或sumo-gui）
2. traci.start ：启动SUMO进程并建立连接
3. simulationStep ：推进仿真一步
4. vehicle.getIDList ：获取当前所有车辆ID
5. vehicle.getPosition ：获取指定车辆的位置

4.2 运行准备

在运行脚本前，需要准备：

1. SUMO配置文件（.sumocfg）
2. 对应的路网文件（.net.xml）
3. 可能的车辆路由文件（.rou.xml）

将这些文件放在同一目录下，并修改脚本中的配置文件路径。

5. 高级配置与性能优化

当基本功能运行正常后，可以考虑以下优化措施提升开发体验和仿真效率：

5.1 使用SUMO的Python工具库

SUMO提供了丰富的Python工具，可以简化路网生成、车辆路径规划等操作：

from sumolib import net
road_network = net.readNet('your_network.net.xml')
edges = road_network.getEdges()
for edge in edges:
    print(edge.getID(), edge.getLength())

5.2 批量仿真与参数调优

通过调整SUMO的仿真参数，可以提高大规模路网的仿真速度：

sumoCmd = [
    sumoBinary,
    "-c", "config.sumocfg",
    "--no-step-log",  # 减少日志输出
    "--no-warnings",  # 忽略警告
    "--time-to-teleport", "-1",  # 禁用车辆传送
    "--collision.action", "warn"  # 碰撞处理方式
]

5.3 可视化与调试技巧

在开发过程中，可以利用SUMO-GUI的可视化功能辅助调试：

1. 在GUI中查看车辆轨迹
2. 使用"Breakpoint"功能暂停仿真
3. 通过"Delay"滑块控制仿真速度
4. 使用"View Settings"自定义显示内容

6. 实际项目中的经验分享

在长期使用SUMO进行交通仿真的过程中，积累了一些实用技巧：

• 路径处理 ：使用 os.path 模块处理路径，避免硬编码：

import os
config_path = os.path.join('simulation', 'configs', 'large_network.sumocfg')

• 异常处理 ：为TraCI操作添加异常捕获，防止仿真意外终止：

try:
    traci.simulationStep()
except traci.TraCIException as e:
    print(f"仿真出错: {e}")
    # 处理错误或重新连接

• 性能监控 ：在长时间仿真中监控资源使用情况：

import psutil
process = psutil.Process()
print(f"内存使用: {process.memory_info().rss / 1024 / 1024:.2f} MB")

• 批量测试 ：编写自动化脚本测试不同参数组合：

import itertools

for demand, timing in itertools.product([1000, 2000, 3000], [0.5, 1.0, 1.5]):
    run_simulation(vehicle_demand=demand, traffic_light_timing=timing)