Webots 教程1软件安装与环境配置完全指南——二十年仿真老兵的开篇忠告版本声明块仿真软件Webots R2025a2025 年 1 月 31 日发布控制器语言Python 3.8推荐 3.10/3.11测试平台Windows 11 23H2 / Ubuntu 22.04 LTS / macOS 14硬件要求OpenGL 3.3 显卡、8GB 内存16GB 更佳系列规划共 20 篇覆盖入门到完整项目实战〇、写在系列开头为什么选择 Webots在动笔之前我有必要先讲清楚一个选型问题——因为在机器人仿真这个领域工具的选择直接决定了你未来两年的工作体验。我是从 2006 年前后开始接触机器人仿真的那时候的选择基本只有 Webots商业授权一个 license 上千欧元和自研的简化 2D 环境。后来 Gazebo 随着 ROS 崛起 CoppeliaSim原 V-REP走轻量路线 isaac gym/isaac sim 主打 GPU 并行。2020 年 Cyberbotics 把 Webots 完全开源Apache 2.0之后这个格局发生了微妙变化。今天如果你问我为什么仍然推荐 Webots 作为系统性学习的平台理由有三条第一文档质量是同类工具中最好的。Webots 的官方文档有完整的 API 参考、循序渐进的指南、以及每个功能节点的详细说明。相比之下某些开源仿真器的文档残缺不全学习成本主要在猜上。第二传感器与执行器模型的保真度设计合理。Webots 对传感器噪声、延迟、物理特性的建模足够真实但不至于让初学者陷入调参地狱。红外传感器会受物体材质影响黑色物体反射弱激光雷达有距离限制这些特性与真实硬件一致——你在仿真里养成的直觉可以迁移到实机上。第三跨语言控制器支持成熟。C、C、Python、Java、MATLAB 五种语言的 API 逐函数对应这意味着团队里算法工程师用 Python 快速验证、嵌入式工程师用 C 部署的协作模式可以无缝衔接。当然 Webots 也有短板GPU 并行仿真能力不如 Isaac Sim做大规模强化学习训练时是硬伤、生态规模不如 Gazebo第三方模型和插件少。但作为学习机器人仿真原理和中小规模算法验证的平台它至今仍是平衡性最好的选择之一。一、理解 Webots 的技术架构安装之前先建立架构认知这能帮你理解后面所有配置行为的为什么。Webots 由四个核心子系统构成┌────────────────────────────────────────────────┐ │ Webots 主进程 │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │ │ │ 3D 渲染 │ │ 场景管理 │ │ 仿真调度器 │ │ │ │ (OpenGL) │ │ (场景树) │ │ (时间步进控制) │ │ │ └──────────┘ └──────────┘ └──────────────┘ │ │ │ │ │ ┌────────┴────────┐ │ │ │ ODE 物理引擎 │ │ │ │ (刚体动力学求解) │ │ │ └────────┬────────┘ │ ├───────────────────────┼──────────────────────────┤ │ 进程间通信通道 │ ├───────┬───────┬───────┴──────┬─────────┬────────┤ │控制器A │控制器B │控制器C │ 控制器D │ ... │ │(Python)│(C) │(C) │(Python) │ │ │独立进程│独立进程 │独立进程 │独立进程 │ │ └───────┴───────┴──────────────┴─────────┴────────┘关键设计决策每个机器人控制器是独立的操作系统进程。这个架构决策带来几个深远影响故障隔离——一台机器人的控制器崩溃不会拖垮整个仿真这在调试阶段极其宝贵语言自由——进程间通过管道通信用什么语言实现控制器无关紧要真实性强——真实机器人系统里控制器也是独立计算单元仿真架构与真实架构同构性能代价——进程切换和 IPC 有开销这也是 Webots 在大规模并行仿真上不如 GPU 原生仿真器的架构性原因理解了控制器是独立进程你就能理解后面教程里的很多行为为什么print()输出出现在 Webots 控制台stdout 被重定向、为什么控制器崩溃后 Webots 本体不崩溃、为什么多机器人仿真时 CPU 占用与机器人数量成正比。物理引擎采用 ODEOpen Dynamics Engine。这是一个经典的刚体动力学求解器处理碰撞检测、约束求解、关节动力学。Webots 在 ODE 之上封装了自己的关节/接触模型。ODE 的特点是稳定、成熟、但单线程——这决定了 Webots 的物理计算不能通过多核加速渲染和控制可以物理不行。做大规模仿真时的性能瓶颈通常就在物理引擎这一层。二、R2025a 版本深度解读每一版 Webots 的变更日志都值得仔细读因为它直接影响你的代码能否运行。R2025a 的变更里有几条对教程内容有决定性影响2.1 ROS 1 支持被彻底移除这不是简单的弃用警告是删除。如果你的旧项目基于 ROS 1webots_ros 包迁移到 R2025a 后将完全无法工作。官方给出的迁移路径是 webots_ros2 包第 18 篇详述。对新高学的启示不要学 ROS 1直接上 ROS 2。ROS 1Noetic 是最后 LTS 版官方支持已在收尾新项目没有理由再入这个坑。2.2 Lua 作为 PROTO 脚本语言被移除PROTO 模板现在只能用 JavaScript。历史上 Webots 支持 Lua 写动态模板根据参数生成节点结构R2025a 起这条路断了。旧教程里% ... %的 Lua 语法全部作废统一改为%{ ... }%的 JS 语法。2.3 Supervisor API 更名wb_supervisor_node_get_proto_*系列函数更名为wb_supervisor_node_get_base_node_*。这是一次语义修正这些函数查询的是基础节点而非 PROTO 实例但对你意味着网上 2024 年及更早的 Supervisor 教程代码直接抄会报编译错误。2.4 X3D 更名为 W3DWeb 导出格式改名。做 3D 可视化集成的项目需要注意。2.5 系统要求变化支持状态系统新增支持Ubuntu 24.04、macOS 14移除支持Ubuntu 20.04、macOS 11Ubuntu 20.04 用户面临升级。考虑到 22.04 是 ROS 2 Humble 的基准平台推荐 Ubuntu 22.04 作为 Linux 上的主力组合。三、下载与安装实操3.1 获取安装包官方发布渠道有两个GitHub Releasesgithub.com/cyberbotics/webots/releases——版本最全包含 nightly buildCyberbotics 官网cyberbotics.com——提供稳定版国内网络环境访问 GitHub 可能缓慢实测以下方式可行使用 GitHub 加速代理如 ghproxy 类镜像、或从官网直接下载。安装包体积约 500MB包含了完整的模型库projects 目录和文档。版本选择建议学习和开发用 R2025a 稳定版需要某个尚未发布的新功能时才考虑 nightly build不稳定随时可能有 breaking change。不要在团队项目里混用版本——.wbt 文件头部的版本号标识了创建版本跨版本打开可能出现字段兼容问题。3.2 Windows 安装细节双击webots-x64-setup.exe后安装向导基本可以一路默认但有三个细节值得专门说明细节一安装路径必须是纯英文。这是 Windows 平台的第一大坑。Webots 的控制器编译MinGW 调用和 Python 模块加载都会解析路径中文路径如D:\文档\在某些环节会出现编码问题。典型症状C 控制器编译时报gcc: error: No such file or directoryPython 控制器启动报ModuleNotFoundError: No module named controller世界文件加载后模型显示异常推荐安装到C:\Program Files\Webots默认或D:\webots\R2025a自定义盘符时保持纯英文。同理你的 Webots 项目目录也必须全英文——这个坑在教程学员里的出现频率高到值得我在第一篇就反复强调。细节二不需要配置任何环境变量。Webots 是自包含的绿色结构它自带 MinGW 编译器编译 C/C 控制器、自带 Python 运行时运行内置 Python 控制器、自带所有依赖库。安装完成后双击桌面图标即可运行没有任何环境变量要设。网上某些老教程让你配WEBOTS_HOME——那是做深度开发比如自己编译 Webots 源码、开发插件时才需要的普通使用完全不必。细节三杀毒软件可能干扰编译。C/C 控制器首次编译时MinGW 的编译进程gcc.exe可能被杀毒软件误判拦截表现为控制器一直显示compiling…或直接编译失败。解决方案把 Webots 安装目录加入杀毒软件白名单。这个问题在国产杀毒软件上出现率较高。3.3 Linux 安装Ubuntu 22.04/24.04 的 deb 安装# 安装 deb 包sudodpkg-iwebots_R2025a_amd64.deb# 如有依赖缺失自动补齐sudoapt-getinstall-f安装完成后命令行输入webots或从应用菜单启动。Linux 版的一个优势可以直接从源码编译如果你需要修改 Webots 本体或调试渲染问题源码仓库里有完整的编译说明。常见依赖问题显卡驱动。Linux 下的 OpenGL 支持依赖正确的显卡驱动配置NVIDIA 卡需要官方闭源驱动开源 nouveau 驱动在部分场景下有渲染问题。如果 3D 视图出现渲染错误或黑屏先检查glxinfo | grep OpenGL version确认驱动状态。3.4 macOS 安装双击 dmg 拖入 Applications。Apple SiliconM 系列芯片上运行 Intel 版 Webots 需要 Rosetta 2 转译首次启动系统会提示安装。macOS 的一个已知特性Gatekeeper 安全机制可能拦截未签名/未公证的二进制。如果启动被拦到「系统设置 → 隐私与安全性」底部点击「仍要打开」。四、验证安装跑通第一个仿真安装成功的判断标准不是程序能打开而是**“官方示例能完整仿真”**。这里面包含了对渲染管线、物理引擎、控制器编译、进程通信四个子系统的全面验证。4.1 标准验证流程第一步打开官方教程世界菜单File → Open Sample World在文件对话框中导航到projects → samples → tutorials → worlds → my_first_simulation.wbt这个场景包含一个带纹理的地面RectangleArena、一个 e-puck 机器人、以及一个演示用的控制器。第二步启动仿真点击工具栏的播放按钮▶。此时 Webots 会依次做四件事编译/启动控制器进程e-puck 的控制器初始化 ODE 物理引擎加载所有物体的碰撞体和物理属性开始时间步进每个 basicTimeStep 执行一轮物理计算 → 传感器刷新 → 控制器步进渲染管线持续绘制 3D 视图第三步确认三个现象✅ e-puck 机器人开始向前移动说明控制器 → 电机链路正常✅ 机器人在围墙处停下说明物理碰撞检测正常✅ 底部控制台有持续滚动的传感器数值输出说明传感器 → 控制器链路正常三个现象同时出现安装验证才算通过。任何一项缺失都指向特定子系统的问题缺失现象问题定位机器人不动控制器编译失败看控制台报错或电机配置问题机器人穿墙物理引擎异常boundingObject 缺失或显卡驱动问题控制台无输出stdout 重定向失败罕见通常是安装损坏4.2 初识仿真控制验证时顺手体验三个控制操作它们是后面所有调试工作的基础暂停/继续工具栏 ⏸——冻结仿真时间控制器进程暂停在 step() 调用上单步执行工具栏 ⏭——前进一个 basicTimeStep是逐帧调试的利器重置仿真工具栏 ↺——回到初始状态杀掉控制器进程并重启特别说明重置的行为它不只是把物体搬回原位而是完全重启控制器进程。控制器里的全局变量、已建立的状态全部清零。这个语义在后面写代码时很重要——不要期望重置后还能保留上次的运行数据。五、Python 环境深度配置Webots 与 Python 的关系值得单独用一节讲清楚因为这里的配置直接决定你能不能用 numpy/cv2 这些科学计算库。5.1 Webots 的 Python 支持机制Webots 支持两种 Python 使用模式模式一使用 Webots 内置 Python。安装包自带一个精简 Python 运行时开箱即用。但这个 Python 无法安装第三方库或者装起来很别扭只适合纯标准库的控制器。模式二使用系统 Python。Webots 启动 Python 控制器时会按以下顺序查找解释器WEBOTS_HOME环境变量指定的路径关联配置系统 PATH 里的python命令Linux/macOS或pylauncherWindowsWebots 内置的 Python兜底做正经开发必须用模式二——你迟早需要 numpy 处理激光数据、用 opencv 处理相机图像这些库只能装在系统 Python 里。5.2 配置系统 Python确认版本python--version# 需要 3.8验证 Webots 能找到正确的 Python。在控制器里打印解释器路径# check_python.py —— 放在任意控制器的开头运行importsysprint(Python 解释器:,sys.executable)print(Python 版本:,sys.version)如果输出的路径不是你预期的比如指向了 Webots 内置目录有两个干预手段在Tools → Preferences → Python command里显式指定解释器路径设置环境变量后重启 Webots安装第三方库到正确的解释器。最常见的错误场景你在系统里用pip install numpy装了库但 Webots 用的是另一个 Python比如 conda 环境与系统环境不一致。症状是控制器报ModuleNotFoundError。解法就是上面的 print 大法确认路径然后用那个解释器的 pip 装库# 用绝对路径调用 pip确保装到 Webots 实际使用的解释器C:\Python311\python.exe-mpipinstallnumpy opencv-python5.3 虚拟环境的取舍Python 虚拟环境venv/conda在 Webots 里的支持是能用但不顺滑。Webots 偏好全局解释器虚拟环境需要在 Preferences 里显式指定激活后的 python 路径。我的建议学习阶段直接用系统 Python工程阶段再考虑虚拟环境隔离。机器人仿真项目的依赖冲突远没有 Web 开发那么严重为虚拟环境增加的配置摩擦在学习阶段不值当。六、项目目录结构必须一开始就遵守的规范Webots 对项目结构有强约定。不符合结构的项目无法正常关联控制器这是新手第二大坑第一大是中文路径。6.1 标准结构my_project/ ├── controllers/ # 控制器根目录名字固定 │ ├── my_controller_a/ # 每个控制器一个子目录 │ │ ├── my_controller_a.py # 主文件名字必须与目录一致 │ │ └── helper_module.py # 可放辅助模块 │ └── my_controller_b/ │ ├── Makefile # C/C 控制器需要Python 不需要 │ └── my_controller_b.c ├── protos/ # 项目级 PROTO 模型 │ └── MyRobot.proto ├── plugins/ # 高级扩展物理插件等可选 │ ├── physics/ │ └── robot_windows/ ├── worlds/ # 世界文件目录 │ ├── my_world.wbt # 世界文件项目入口 │ ├── .my_world.wbproj # 隐藏项目文件GUI 状态 │ └── textures/ # 贴图资源 └── .gitignore # 版本管理用6.2 三条铁律的原理铁律一目录名即控制器名。世界文件里 Robot 节点写controller my_controller_aWebots 就去controllers/my_controller_a/找my_controller_a.py或 .c。这个名字匹配是三层一致的世界文件字段值 控制器目录名 主文件名。任何一层对不上Webots 找不到控制器并回退到 void机器人不动控制台可能无报错——这个静默失败很容易让人怀疑人生。铁律二世界文件是项目入口。所有相对路径贴图、PROTO、模型文件都以 .wbt 文件所在目录为基准解析。用File → Open World打开世界文件就是打开项目。铁律三Python 免 MakefileC 必须 Makefile。Python 控制器是解释执行的放个 .py 文件就能跑。C/C 控制器需要编译Makefile 由向导自动生成定义链接 Webots 库的规则。用Wizards → New Robot Controller创建 C 控制器会自动带出 Makefile。6.3 创建项目的正确方式不要手动建目录——用向导File → New → New Project Directory向导会问你要不要 RectangleArena建议要白送的地面和围墙以及项目路径必须全英文。生成后再用Wizards → New Robot Controller创建控制器向导自动处理目录结构和世界文件的关联。6.4 版本管理建议用 Git 管理项目时忽略以下内容# .gitignore *.wbproj # GUI 布局状态每人不同 *.jpg # 世界缩略图 controllers/*/ # 编译产物C 控制器的可执行文件 *.exe *.o.wbt、.proto、controllers/*/*.py、controllers/*/*.c这些源文件全部入库。七、安装问题系统排查二十年里我见过大量安装问题按出现频率排序列出解法问题 1控制器编译报错Windows 高发症状C 控制器编译报gcc: error或一直卡在编译状态。排查顺序检查项目路径和安装路径是否含中文/空格 → 改纯英文路径杀毒软件是否拦截 gcc.exe → 加白名单重启 Webots 后重试编译缓存偶发损坏问题 2Python 控制器报 ModuleNotFoundError: ‘controller’症状控制台输出ModuleNotFoundError: No module named controller。根因你用python xxx.py直接运行了控制器文件。controller模块不在标准库路径里它由 Webots 启动控制器时注入。正解控制器只能由 Webots 启动。打开包含该控制器的世界文件点播放。如果你确实需要独立运行某段逻辑做单元测试把那段逻辑抽成不依赖 controller 模块的纯函数库。问题 33D 视图黑屏或渲染异常排查顺序更新显卡驱动80% 的渲染问题由此解决Tools → Preferences → OpenGL关闭抗锯齿确认显卡支持 OpenGL 3.3十年内的显卡都没问题虚拟机里的集成显卡可能不行问题 4Linux 缺少共享库症状启动报error while loading shared libraries: libXXX.so。解法sudo apt-get install -f补依赖。Ubuntu 24.04 用户注意R2025a 才开始支持该版本老版 Webots 在其上有已知兼容问题。问题 5仿真运行极慢先分清两种慢仿真时钟慢于真实时钟标题栏显示 x0.5 等→ 物理计算或控制器负载重属于性能问题第 19 篇专讲界面卡顿但仿真时钟正常→ 渲染负载重关抗锯齿/简化场景问题 6多显示器环境下界面错位Webots 的 GUI 在部分多显示器/高 DPI 配置下有布局问题。Tools → Preferences里有界面缩放设置可调。八、给初学者的路线图装好环境只是第一步。给出后续 19 篇的学习路线帮你建立全局预期阶段一第 1-4 篇 入门基础 安装配置 → IDE 界面 → 第一个控制器 → 场景文件语法 目标能独立跑通并看懂一个 Webots 项目 阶段二第 5-8 篇 核心编程 控制器模型 → 电机三模式 → 传感器与避障 → 差速运动学 目标能从零控制机器人完成感知-决策-执行闭环 阶段三第 9-12 篇 进阶感知 相机视觉 → 激光建图 → 定位融合 → Supervisor 目标掌握机器人主流传感器和仿真监控 阶段四第 13-16 篇 高级主题 机械臂建模 → PROTO 封装 → 物理调优 → 多机通信 目标能构建自定义多机器人系统 阶段五第 17-20 篇 实战应用 路径规划 → ROS 2 集成 → 性能优化 → 完整仓储项目 目标具备独立完成仿真项目的工程能力每篇遵循统一结构版本声明 → 问题定义 → 原理讲解 → 完整代码 → 排错指南 → 小结。代码全部基于 R2025a 真实 API可以直接复制运行。九、本篇小结本篇完成三件事建立 Webots 的架构认知进程模型、ODE 物理引擎、完成 R2025a 安装与验证、固化项目结构规范。三个最重要的要点路径必须全英文——Windows 第一大坑中文路径会导致编译和模块加载的诡异故障控制器是独立进程——理解这一点后面所有为什么都有了答案验证安装的标准是完整仿真——不是能打开而是示例能跑通三要素移动/碰撞/输出下一篇系统讲解 Webots IDE 的四大区域重点解剖场景树——它是后面 18 篇里所有建模配置操作的唯一入口。本系列下一篇《Webots 教程2IDE 界面认识与基本操作》
Webots教程（1）：软件安装与环境配置完全指南——二十年仿真老兵的开篇忠告
Webots 教程1软件安装与环境配置完全指南——二十年仿真老兵的开篇忠告版本声明块仿真软件Webots R2025a2025 年 1 月 31 日发布控制器语言Python 3.8推荐 3.10/3.11测试平台Windows 11 23H2 / Ubuntu 22.04 LTS / macOS 14硬件要求OpenGL 3.3 显卡、8GB 内存16GB 更佳系列规划共 20 篇覆盖入门到完整项目实战〇、写在系列开头为什么选择 Webots在动笔之前我有必要先讲清楚一个选型问题——因为在机器人仿真这个领域工具的选择直接决定了你未来两年的工作体验。我是从 2006 年前后开始接触机器人仿真的那时候的选择基本只有 Webots商业授权一个 license 上千欧元和自研的简化 2D 环境。后来 Gazebo 随着 ROS 崛起 CoppeliaSim原 V-REP走轻量路线 isaac gym/isaac sim 主打 GPU 并行。2020 年 Cyberbotics 把 Webots 完全开源Apache 2.0之后这个格局发生了微妙变化。今天如果你问我为什么仍然推荐 Webots 作为系统性学习的平台理由有三条第一文档质量是同类工具中最好的。Webots 的官方文档有完整的 API 参考、循序渐进的指南、以及每个功能节点的详细说明。相比之下某些开源仿真器的文档残缺不全学习成本主要在猜上。第二传感器与执行器模型的保真度设计合理。Webots 对传感器噪声、延迟、物理特性的建模足够真实但不至于让初学者陷入调参地狱。红外传感器会受物体材质影响黑色物体反射弱激光雷达有距离限制这些特性与真实硬件一致——你在仿真里养成的直觉可以迁移到实机上。第三跨语言控制器支持成熟。C、C、Python、Java、MATLAB 五种语言的 API 逐函数对应这意味着团队里算法工程师用 Python 快速验证、嵌入式工程师用 C 部署的协作模式可以无缝衔接。当然 Webots 也有短板GPU 并行仿真能力不如 Isaac Sim做大规模强化学习训练时是硬伤、生态规模不如 Gazebo第三方模型和插件少。但作为学习机器人仿真原理和中小规模算法验证的平台它至今仍是平衡性最好的选择之一。一、理解 Webots 的技术架构安装之前先建立架构认知这能帮你理解后面所有配置行为的为什么。Webots 由四个核心子系统构成┌────────────────────────────────────────────────┐ │ Webots 主进程 │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │ │ │ 3D 渲染 │ │ 场景管理 │ │ 仿真调度器 │ │ │ │ (OpenGL) │ │ (场景树) │ │ (时间步进控制) │ │ │ └──────────┘ └──────────┘ └──────────────┘ │ │ │ │ │ ┌────────┴────────┐ │ │ │ ODE 物理引擎 │ │ │ │ (刚体动力学求解) │ │ │ └────────┬────────┘ │ ├───────────────────────┼──────────────────────────┤ │ 进程间通信通道 │ ├───────┬───────┬───────┴──────┬─────────┬────────┤ │控制器A │控制器B │控制器C │ 控制器D │ ... │ │(Python)│(C) │(C) │(Python) │ │ │独立进程│独立进程 │独立进程 │独立进程 │ │ └───────┴───────┴──────────────┴─────────┴────────┘关键设计决策每个机器人控制器是独立的操作系统进程。这个架构决策带来几个深远影响故障隔离——一台机器人的控制器崩溃不会拖垮整个仿真这在调试阶段极其宝贵语言自由——进程间通过管道通信用什么语言实现控制器无关紧要真实性强——真实机器人系统里控制器也是独立计算单元仿真架构与真实架构同构性能代价——进程切换和 IPC 有开销这也是 Webots 在大规模并行仿真上不如 GPU 原生仿真器的架构性原因理解了控制器是独立进程你就能理解后面教程里的很多行为为什么print()输出出现在 Webots 控制台stdout 被重定向、为什么控制器崩溃后 Webots 本体不崩溃、为什么多机器人仿真时 CPU 占用与机器人数量成正比。物理引擎采用 ODEOpen Dynamics Engine。这是一个经典的刚体动力学求解器处理碰撞检测、约束求解、关节动力学。Webots 在 ODE 之上封装了自己的关节/接触模型。ODE 的特点是稳定、成熟、但单线程——这决定了 Webots 的物理计算不能通过多核加速渲染和控制可以物理不行。做大规模仿真时的性能瓶颈通常就在物理引擎这一层。二、R2025a 版本深度解读每一版 Webots 的变更日志都值得仔细读因为它直接影响你的代码能否运行。R2025a 的变更里有几条对教程内容有决定性影响2.1 ROS 1 支持被彻底移除这不是简单的弃用警告是删除。如果你的旧项目基于 ROS 1webots_ros 包迁移到 R2025a 后将完全无法工作。官方给出的迁移路径是 webots_ros2 包第 18 篇详述。对新高学的启示不要学 ROS 1直接上 ROS 2。ROS 1Noetic 是最后 LTS 版官方支持已在收尾新项目没有理由再入这个坑。2.2 Lua 作为 PROTO 脚本语言被移除PROTO 模板现在只能用 JavaScript。历史上 Webots 支持 Lua 写动态模板根据参数生成节点结构R2025a 起这条路断了。旧教程里% ... %的 Lua 语法全部作废统一改为%{ ... }%的 JS 语法。2.3 Supervisor API 更名wb_supervisor_node_get_proto_*系列函数更名为wb_supervisor_node_get_base_node_*。这是一次语义修正这些函数查询的是基础节点而非 PROTO 实例但对你意味着网上 2024 年及更早的 Supervisor 教程代码直接抄会报编译错误。2.4 X3D 更名为 W3DWeb 导出格式改名。做 3D 可视化集成的项目需要注意。2.5 系统要求变化支持状态系统新增支持Ubuntu 24.04、macOS 14移除支持Ubuntu 20.04、macOS 11Ubuntu 20.04 用户面临升级。考虑到 22.04 是 ROS 2 Humble 的基准平台推荐 Ubuntu 22.04 作为 Linux 上的主力组合。三、下载与安装实操3.1 获取安装包官方发布渠道有两个GitHub Releasesgithub.com/cyberbotics/webots/releases——版本最全包含 nightly buildCyberbotics 官网cyberbotics.com——提供稳定版国内网络环境访问 GitHub 可能缓慢实测以下方式可行使用 GitHub 加速代理如 ghproxy 类镜像、或从官网直接下载。安装包体积约 500MB包含了完整的模型库projects 目录和文档。版本选择建议学习和开发用 R2025a 稳定版需要某个尚未发布的新功能时才考虑 nightly build不稳定随时可能有 breaking change。不要在团队项目里混用版本——.wbt 文件头部的版本号标识了创建版本跨版本打开可能出现字段兼容问题。3.2 Windows 安装细节双击webots-x64-setup.exe后安装向导基本可以一路默认但有三个细节值得专门说明细节一安装路径必须是纯英文。这是 Windows 平台的第一大坑。Webots 的控制器编译MinGW 调用和 Python 模块加载都会解析路径中文路径如D:\文档\在某些环节会出现编码问题。典型症状C 控制器编译时报gcc: error: No such file or directoryPython 控制器启动报ModuleNotFoundError: No module named controller世界文件加载后模型显示异常推荐安装到C:\Program Files\Webots默认或D:\webots\R2025a自定义盘符时保持纯英文。同理你的 Webots 项目目录也必须全英文——这个坑在教程学员里的出现频率高到值得我在第一篇就反复强调。细节二不需要配置任何环境变量。Webots 是自包含的绿色结构它自带 MinGW 编译器编译 C/C 控制器、自带 Python 运行时运行内置 Python 控制器、自带所有依赖库。安装完成后双击桌面图标即可运行没有任何环境变量要设。网上某些老教程让你配WEBOTS_HOME——那是做深度开发比如自己编译 Webots 源码、开发插件时才需要的普通使用完全不必。细节三杀毒软件可能干扰编译。C/C 控制器首次编译时MinGW 的编译进程gcc.exe可能被杀毒软件误判拦截表现为控制器一直显示compiling…或直接编译失败。解决方案把 Webots 安装目录加入杀毒软件白名单。这个问题在国产杀毒软件上出现率较高。3.3 Linux 安装Ubuntu 22.04/24.04 的 deb 安装# 安装 deb 包sudodpkg-iwebots_R2025a_amd64.deb# 如有依赖缺失自动补齐sudoapt-getinstall-f安装完成后命令行输入webots或从应用菜单启动。Linux 版的一个优势可以直接从源码编译如果你需要修改 Webots 本体或调试渲染问题源码仓库里有完整的编译说明。常见依赖问题显卡驱动。Linux 下的 OpenGL 支持依赖正确的显卡驱动配置NVIDIA 卡需要官方闭源驱动开源 nouveau 驱动在部分场景下有渲染问题。如果 3D 视图出现渲染错误或黑屏先检查glxinfo | grep OpenGL version确认驱动状态。3.4 macOS 安装双击 dmg 拖入 Applications。Apple SiliconM 系列芯片上运行 Intel 版 Webots 需要 Rosetta 2 转译首次启动系统会提示安装。macOS 的一个已知特性Gatekeeper 安全机制可能拦截未签名/未公证的二进制。如果启动被拦到「系统设置 → 隐私与安全性」底部点击「仍要打开」。四、验证安装跑通第一个仿真安装成功的判断标准不是程序能打开而是**“官方示例能完整仿真”**。这里面包含了对渲染管线、物理引擎、控制器编译、进程通信四个子系统的全面验证。4.1 标准验证流程第一步打开官方教程世界菜单File → Open Sample World在文件对话框中导航到projects → samples → tutorials → worlds → my_first_simulation.wbt这个场景包含一个带纹理的地面RectangleArena、一个 e-puck 机器人、以及一个演示用的控制器。第二步启动仿真点击工具栏的播放按钮▶。此时 Webots 会依次做四件事编译/启动控制器进程e-puck 的控制器初始化 ODE 物理引擎加载所有物体的碰撞体和物理属性开始时间步进每个 basicTimeStep 执行一轮物理计算 → 传感器刷新 → 控制器步进渲染管线持续绘制 3D 视图第三步确认三个现象✅ e-puck 机器人开始向前移动说明控制器 → 电机链路正常✅ 机器人在围墙处停下说明物理碰撞检测正常✅ 底部控制台有持续滚动的传感器数值输出说明传感器 → 控制器链路正常三个现象同时出现安装验证才算通过。任何一项缺失都指向特定子系统的问题缺失现象问题定位机器人不动控制器编译失败看控制台报错或电机配置问题机器人穿墙物理引擎异常boundingObject 缺失或显卡驱动问题控制台无输出stdout 重定向失败罕见通常是安装损坏4.2 初识仿真控制验证时顺手体验三个控制操作它们是后面所有调试工作的基础暂停/继续工具栏 ⏸——冻结仿真时间控制器进程暂停在 step() 调用上单步执行工具栏 ⏭——前进一个 basicTimeStep是逐帧调试的利器重置仿真工具栏 ↺——回到初始状态杀掉控制器进程并重启特别说明重置的行为它不只是把物体搬回原位而是完全重启控制器进程。控制器里的全局变量、已建立的状态全部清零。这个语义在后面写代码时很重要——不要期望重置后还能保留上次的运行数据。五、Python 环境深度配置Webots 与 Python 的关系值得单独用一节讲清楚因为这里的配置直接决定你能不能用 numpy/cv2 这些科学计算库。5.1 Webots 的 Python 支持机制Webots 支持两种 Python 使用模式模式一使用 Webots 内置 Python。安装包自带一个精简 Python 运行时开箱即用。但这个 Python 无法安装第三方库或者装起来很别扭只适合纯标准库的控制器。模式二使用系统 Python。Webots 启动 Python 控制器时会按以下顺序查找解释器WEBOTS_HOME环境变量指定的路径关联配置系统 PATH 里的python命令Linux/macOS或pylauncherWindowsWebots 内置的 Python兜底做正经开发必须用模式二——你迟早需要 numpy 处理激光数据、用 opencv 处理相机图像这些库只能装在系统 Python 里。5.2 配置系统 Python确认版本python--version# 需要 3.8验证 Webots 能找到正确的 Python。在控制器里打印解释器路径# check_python.py —— 放在任意控制器的开头运行importsysprint(Python 解释器:,sys.executable)print(Python 版本:,sys.version)如果输出的路径不是你预期的比如指向了 Webots 内置目录有两个干预手段在Tools → Preferences → Python command里显式指定解释器路径设置环境变量后重启 Webots安装第三方库到正确的解释器。最常见的错误场景你在系统里用pip install numpy装了库但 Webots 用的是另一个 Python比如 conda 环境与系统环境不一致。症状是控制器报ModuleNotFoundError。解法就是上面的 print 大法确认路径然后用那个解释器的 pip 装库# 用绝对路径调用 pip确保装到 Webots 实际使用的解释器C:\Python311\python.exe-mpipinstallnumpy opencv-python5.3 虚拟环境的取舍Python 虚拟环境venv/conda在 Webots 里的支持是能用但不顺滑。Webots 偏好全局解释器虚拟环境需要在 Preferences 里显式指定激活后的 python 路径。我的建议学习阶段直接用系统 Python工程阶段再考虑虚拟环境隔离。机器人仿真项目的依赖冲突远没有 Web 开发那么严重为虚拟环境增加的配置摩擦在学习阶段不值当。六、项目目录结构必须一开始就遵守的规范Webots 对项目结构有强约定。不符合结构的项目无法正常关联控制器这是新手第二大坑第一大是中文路径。6.1 标准结构my_project/ ├── controllers/ # 控制器根目录名字固定 │ ├── my_controller_a/ # 每个控制器一个子目录 │ │ ├── my_controller_a.py # 主文件名字必须与目录一致 │ │ └── helper_module.py # 可放辅助模块 │ └── my_controller_b/ │ ├── Makefile # C/C 控制器需要Python 不需要 │ └── my_controller_b.c ├── protos/ # 项目级 PROTO 模型 │ └── MyRobot.proto ├── plugins/ # 高级扩展物理插件等可选 │ ├── physics/ │ └── robot_windows/ ├── worlds/ # 世界文件目录 │ ├── my_world.wbt # 世界文件项目入口 │ ├── .my_world.wbproj # 隐藏项目文件GUI 状态 │ └── textures/ # 贴图资源 └── .gitignore # 版本管理用6.2 三条铁律的原理铁律一目录名即控制器名。世界文件里 Robot 节点写controller my_controller_aWebots 就去controllers/my_controller_a/找my_controller_a.py或 .c。这个名字匹配是三层一致的世界文件字段值 控制器目录名 主文件名。任何一层对不上Webots 找不到控制器并回退到 void机器人不动控制台可能无报错——这个静默失败很容易让人怀疑人生。铁律二世界文件是项目入口。所有相对路径贴图、PROTO、模型文件都以 .wbt 文件所在目录为基准解析。用File → Open World打开世界文件就是打开项目。铁律三Python 免 MakefileC 必须 Makefile。Python 控制器是解释执行的放个 .py 文件就能跑。C/C 控制器需要编译Makefile 由向导自动生成定义链接 Webots 库的规则。用Wizards → New Robot Controller创建 C 控制器会自动带出 Makefile。6.3 创建项目的正确方式不要手动建目录——用向导File → New → New Project Directory向导会问你要不要 RectangleArena建议要白送的地面和围墙以及项目路径必须全英文。生成后再用Wizards → New Robot Controller创建控制器向导自动处理目录结构和世界文件的关联。6.4 版本管理建议用 Git 管理项目时忽略以下内容# .gitignore *.wbproj # GUI 布局状态每人不同 *.jpg # 世界缩略图 controllers/*/ # 编译产物C 控制器的可执行文件 *.exe *.o.wbt、.proto、controllers/*/*.py、controllers/*/*.c这些源文件全部入库。七、安装问题系统排查二十年里我见过大量安装问题按出现频率排序列出解法问题 1控制器编译报错Windows 高发症状C 控制器编译报gcc: error或一直卡在编译状态。排查顺序检查项目路径和安装路径是否含中文/空格 → 改纯英文路径杀毒软件是否拦截 gcc.exe → 加白名单重启 Webots 后重试编译缓存偶发损坏问题 2Python 控制器报 ModuleNotFoundError: ‘controller’症状控制台输出ModuleNotFoundError: No module named controller。根因你用python xxx.py直接运行了控制器文件。controller模块不在标准库路径里它由 Webots 启动控制器时注入。正解控制器只能由 Webots 启动。打开包含该控制器的世界文件点播放。如果你确实需要独立运行某段逻辑做单元测试把那段逻辑抽成不依赖 controller 模块的纯函数库。问题 33D 视图黑屏或渲染异常排查顺序更新显卡驱动80% 的渲染问题由此解决Tools → Preferences → OpenGL关闭抗锯齿确认显卡支持 OpenGL 3.3十年内的显卡都没问题虚拟机里的集成显卡可能不行问题 4Linux 缺少共享库症状启动报error while loading shared libraries: libXXX.so。解法sudo apt-get install -f补依赖。Ubuntu 24.04 用户注意R2025a 才开始支持该版本老版 Webots 在其上有已知兼容问题。问题 5仿真运行极慢先分清两种慢仿真时钟慢于真实时钟标题栏显示 x0.5 等→ 物理计算或控制器负载重属于性能问题第 19 篇专讲界面卡顿但仿真时钟正常→ 渲染负载重关抗锯齿/简化场景问题 6多显示器环境下界面错位Webots 的 GUI 在部分多显示器/高 DPI 配置下有布局问题。Tools → Preferences里有界面缩放设置可调。八、给初学者的路线图装好环境只是第一步。给出后续 19 篇的学习路线帮你建立全局预期阶段一第 1-4 篇 入门基础 安装配置 → IDE 界面 → 第一个控制器 → 场景文件语法 目标能独立跑通并看懂一个 Webots 项目 阶段二第 5-8 篇 核心编程 控制器模型 → 电机三模式 → 传感器与避障 → 差速运动学 目标能从零控制机器人完成感知-决策-执行闭环 阶段三第 9-12 篇 进阶感知 相机视觉 → 激光建图 → 定位融合 → Supervisor 目标掌握机器人主流传感器和仿真监控 阶段四第 13-16 篇 高级主题 机械臂建模 → PROTO 封装 → 物理调优 → 多机通信 目标能构建自定义多机器人系统 阶段五第 17-20 篇 实战应用 路径规划 → ROS 2 集成 → 性能优化 → 完整仓储项目 目标具备独立完成仿真项目的工程能力每篇遵循统一结构版本声明 → 问题定义 → 原理讲解 → 完整代码 → 排错指南 → 小结。代码全部基于 R2025a 真实 API可以直接复制运行。九、本篇小结本篇完成三件事建立 Webots 的架构认知进程模型、ODE 物理引擎、完成 R2025a 安装与验证、固化项目结构规范。三个最重要的要点路径必须全英文——Windows 第一大坑中文路径会导致编译和模块加载的诡异故障控制器是独立进程——理解这一点后面所有为什么都有了答案验证安装的标准是完整仿真——不是能打开而是示例能跑通三要素移动/碰撞/输出下一篇系统讲解 Webots IDE 的四大区域重点解剖场景树——它是后面 18 篇里所有建模配置操作的唯一入口。本系列下一篇《Webots 教程2IDE 界面认识与基本操作》