做机器人仿真的朋友应该都遇到过这个局面装好 Ubuntu 22.04准备跑个 Gazebo结果搜出来的教程一半在讲 Gazebo Classic一半在讲什么 Ignition代码命令还不一样折腾半天版本对不上。这篇文章我专门聊 Gazebo Harmonic——新代 Gazebo 里相当能打的一个版本以及我在 Ubuntu 22.04 上装它、用它的完整经历。要说清楚的不光是“怎么装”还有背后为什么要这么装踩过的坑、调过的参数、最后稳定复现的流程一并写出来给刚入坑的人少走两步弯路。Gazebo Harmonic 属于新一代 Gazebo 仿真器它跟老的 Gazebo Classic 不是同一个东西也不是简单升级。它是从 Ignition Gazebo 这条线改名过来的正式代号按字母表排到了 Harmonic核心包版本是 gz-sim7。对于 Ubuntu 22.04 用户来说Harmonic 是官方明确支持、而且维护期比较长的一个版本跟 ROS 2 Humble 配合也顺。这篇文章适合三类人刚装好 22.04 不知道选哪个 Gazebo 的新手、从 Classic 或者 Fortress 往新版本迁移的老用户、以及需要跑传感器仿真和与 ROS 2 联调的项目开发者。我会从版本选型讲起把三种安装方式全部演示一遍再补充常见问题和排查经验争取你看完就能直接在自己的机器上复现。1. 版本梳理与选型思路1.1 新旧两代 Gazebo大部分人先卡在名字上在我接触的开发者里存在一个很普遍的现象打开终端执行sudo apt install gazebo结果装完之后启动发现界面完全不是网上教程里的样子甚至命令行工具都变了。原因其实很简单——你装的是新代 Gazebo而网上很多教程还在讲 Gazebo Classic 的操作。这两条线的历史发展脉络是这样的。最早大家口中的 Gazebo 是 Gazebo Classic从 1.x 一路做到 11.x老代码里大量用的gazebo命令、gzserver、gzclient都是这条线。后来官方在 2019 年前后启动了新一代架构当时叫 Ignition Gazebo核心目标是重写底层、支持更强的扩展和并发。新代版本为了让玩家容易记住干脆按字母表起代号从 Acropolis、Blueprint、Citadel、Dome、Edifice、Fortress、Garden 一路排下来排到 Harmonic再往后是 Ionic。到了 2022 年左右官方把命名统一新代直接叫 Gazebo去掉了 Ignition 前缀老一代则叫 Gazebo Classic。所以你看到gazebo包名、gz sim命令、gz-sim7这类词都是在说新一代而gazebo9、gazebo11这种带数字的包名以及gzserver这种命令才是 Classic 的东西。如果没搞清楚这条线后面装包、配环境变量的时候很容易被绕进去。注意一点新代 Gazebo 的启动命令是gz sim界面和服务端程序都不再使用gzserver这个名字。如果你执行完gz sim却看到它报了 “cannot find” 或者版本不对多半是系统里同时存在了多个版本gz命令不知道该选谁。这个问题我们在第 5 章专门讲怎么排查。1.2 为什么在 Ubuntu 22.04 上值得升级到 Harmonic版本选型不是越新越好而是看官方支持矩阵和你自己的依赖环境。Gazebo Fortress 当年主要针对 Ubuntu 20.04如果你用 22.04 硬装虽然部分包能装出来但依赖关系和系统库容易打架。Garden 存在的时间较短更像是过渡版本不推荐长期用。Harmonic 往前推的时候官方明确标注支持 Ubuntu 22.04 和 Ubuntu 24.04而且属于长期支持的稳定线社区适配文档也相对齐全这才是它在 22.04 上成为“推荐版本”的根本原因。另外如果你要在 Ubuntu 22.04 上用 ROS 2最常见的发行版就是 Humble。ROS 2 这边的官方桥接包ros_gz对 Harmonic 的适配做得比较早实践下来稳定性和文档完整度都不错。你在 Gazebo 里仿真出来的话题比如激光扫描、里程计、命令速度可以通过桥接进程转到 ROS 2 里不需要自己写复杂的通信中间层。从性能角度讲Harmonic 采用 Entity-Component-SystemECS架构底层实体管理、组件存储和系统调度是分开的多核 CPU 利用率和大型场景加载能力都比 Classic 有明显改善。如果你未来要跑多机器人协同、复杂传感器阵列、动态加载场景这类需求放在 Classic 上会很吃力放在 Harmonic 上会舒服很多。提示如果你的机器还是 Ubuntu 20.04别硬上 Harmonic官方源虽然可能给出部分安装包但依赖和运行库未必匹配老老实实用 Fortress 更省心。22.04 新装系统的前提下直接选 Harmonic 几乎没有悬念。2. 安装前的准备与方案选型2.1 三种安装路径对比我平时最常用的是官方 apt 源Harmonic 在 Ubuntu 22.04 上主要有三种装法各自的定位和适合人群不太一样。我先把三者拉成一张表对比再逐一演算式跑一遍。安装方式核心原理适合场景主要坑点官方 apt 源把 Gazebo 官方软件源加入系统用 apt 直接拉包绝大多数开发者干净、可增量升级需要手动导入 GPG 密钥源配置写错会报错官方安装脚本自动检测系统、配置源并安装包服务器新初始化、不想敲长命令脚本里做的事不透明重复执行可能冲突ROS 2 仓库安装借助 ros-gz 元包拉取 Harmonic 依赖已经装好 ROS 2 Humble 的机器装的是桥接最小集可视化组件可能要补装先说我的结论如果你是一次投入长期使用的机器优先用官方 apt 源。这个方案最透明后续日常更新只要sudo apt update sudo apt upgrade就行。如果你只是想在服务器上快速跑个无头仿真官方安装脚本最省事。要是你已经有一套完整的 ROS 2 Humble 环境那就直接走第三条路省得维护两套源。2.2 安装前的系统检查清单在真正敲命令前建议先花两分钟做一次基础体检后面能省掉大量排查时间。先把这些事情跑一遍。cat /etc/os-release确认当前系统是 jammyUbuntu 22.04而不是 impish 或 lunar。如果输出不对后面的源地址都会出问题因为源里的版本号是自动读取的。sudo apt update sudo apt upgrade -y把系统索引和已有软件包更新到最新避免半路出现依赖冲突。我见过不少人在刚装完系统的状态下直接加新源结果各种依赖解析失败最后还是得回头先执行一遍 update。然后是图形环境的检查。Harmonic 的界面依赖 OpenGL如果你是在物理机上用通常没什么问题但如果是在虚拟机、远程桌面或者容器里后面很可能会出现黑屏或闪退。提前装一个工具摸个底sudo apt install mesa-utils glxinfo -B看到 OpenGL renderer 不是乱码、版本号正常说明图形栈没问题。如果根本没有输出或者提示 failed记下这个情况后面启动时大概率需要软件渲染兜底。虚拟机用户建议直接把虚拟显卡驱动装好或者做好无头模式运行的准备。磁盘方面安装包本身加上依赖大约需要几个 GB 的剩余空间建议至少留出 5 GB避免 Download 到一半磁盘写满导致 apt 缓存损坏。3. 在 Ubuntu 22.04 上装 Harmonic 的完整实操3.1 方式一官方 apt 源安装全流程这是我最推荐的方式下面每一步都给出可直接复制的命令并解释每一条到底是干什么的方便你在出错时定位问题。第一步安装证书工具和下载工具。GPG 密钥导入需要gnupg地址下载需要wget有些精简系统缺这些基础包。sudo apt install lsb-release wget gnupg第二步把 Gazebo 官方签名的 GPG 密钥下载到系统 keyring 目录。这里使用/usr/share/keyrings是为了让 apt 的signed-by能直接引用文件避免把密钥放到不可信位置。sudo wget https://packages.osrfoundation.org/gazebo.gpg -O /usr/share/keyrings/pkgs-osrf-archive-keyring.gpg如果这条命令提示网络超时换个时间重试或者确认你的网络是否能正常访问官方软件源域名。密钥文件下不全会导致后面apt update时报 NO_PUBKEY。第三步向源列表写入 Gazebo 的 apt 源。这条命令比较长我拆开解释echo deb [arch$(dpkg --print-architecture) signed-by/usr/share/keyrings/pkgs-osrf-archive-keyring.gpg] http://packages.osrfoundation.org/gazebo/ubuntu-stable $(lsb_release -cs) main | sudo tee /etc/apt/sources.list.d/gazebo-stable.list$(dpkg --print-architecture)会自动输出 amd64 或 arm64保证架构正确$(lsb_release -cs)自动读取jammy作为发行版代号。所以你复制粘贴执行就行不用手动改字。tee /etc/apt/sources.list.d/gazebo-stable.list的意思是新建一个独立的源文件不污染系统原有源。第四步更新索引并安装主包sudo apt update sudo apt install gazebo这里安装的gazebo是一个元包它会拉取gz-sim7以及配套的gz-transport、gz-common、gz-rendering等组件。安装时间取决于网络一般几分钟内能完。第五步验证版本gz sim --version正常情况下你会看到类似Gazebo Simulator version 7.x.x的输出。如果提示找不到gz命令或者输出的是 Fortress 等其他版本先检查是否设置了正确的版本环境变量方法在 3.4 节。3.2 方式二官方安装脚本一键操作官方提供了一个专门用于 Ubuntu 系系统的安装脚本适合不想一步一步配源的人。脚本入口在 Gazebo 官方工具集仓库执行逻辑和手动 apt 源基本一致只是封装成了自动化命令。sudo curl -o /tmp/ubuntu.sh https://raw.githubusercontent.com/gazebo-tooling/gazebodistro/master/ubuntu.sh chmod x /tmp/ubuntu.sh sudo /tmp/ubuntu.sh install gazebo脚本实际做的事情包括检查你是不是 Ubuntu 或 Debian 系的系统、匹配发行版代号、导入 GPG 密钥、添加gazebo-stable源、最后执行apt install gazebo。可以说它的本质就是 3.1 节的自动化版本。不过脚本方式有两个隐性坑。第一如果你已经手动加过同一个源脚本再次执行时会碰到“重复 deb 源”的报错这时需要先手动清理/etc/apt/sources.list.d/下的旧文件或者直接选择方案 A 不复用脚本。第二脚本对所有用户执行时都可能要求 sudo而它内部重新执行 apt 的权限模型比较依赖当前用户权限所以不要在只读系统或受限用户下强行执行。我更推荐把脚本用在全新初始化的机器上。3.3 方式三通过 ros-humble-ros-gz 间接安装如果你机器上已经有 ROS 2 Humble那么不用单独折腾 Gazebo 官方源直接装桥接包即可sudo apt install ros-humble-ros-gz这个包是一个元包它会把你需要的 Gazebo Harmonic 核心依赖一并拉进来同时安装ros_gz_bridge等与 ROS 2 通信相关的包。装完之后你可以用下面的命令验证gz sim --version ros2 pkg list | grep ros_gz这种方式的优点是依赖关系被 ROS 2 的带包器统一管理很少出现版本不一致缺点也很明显它装的更多是“桥接最小集合”主要面向和 ROS 2 协同使用的场景。如果你之后需要 Gazebo 官方的完整插件库和示例资源可能还要再补sudo apt install gazebo。所以我给的建议是纯仿真用户直接用方式一ROS 2 联调用户优先方式三。3.4 设置 GZ_VERSION 并启动首个场景完成任意一种安装后还有一个容易被忽略但非常重要的一步设置GZ_VERSION环境变量。gz命令本质上是一个多版本入口工具如果系统里只有 Harmonic 一个版本不设置也能大概率正常跑但如果你之前装过 Classic 或者其他旧版gz会不知道选哪个最后可能起错版本。建议直接把环境变量写进当前用户配置让它永久生效echo export GZ_VERSIONharmonic ~/.bashrc source ~/.bashrc然后启动一个内建示例场景试试gz sim -v4 -r shapes.sdf-v4表示日志详细级别调到 4启动时你会在终端里看到加载过程中的报错或警告方便排查-r表示启动后立即开始仿真运行。shapes.sdf是 Harmonic 自带的示例世界文件里面有球体、立方体、圆柱等基础几何体主要用来验证安装是否正常。如果一切正常会弹出一个 GUI 窗口里面有地面和几个几何体模型按下空格键可以暂停/恢复仿真。如果窗口黑屏、闪退或根本没有界面直接跳到第 5 章看排查办法。4. Harmonic 运行机制与关键配置4.1 服务端与客户端分离的架构装好后你会注意到Harmonic 和 Classic 的启动逻辑有本质差别。我们执行gz sim时实际上拉起的是两部分一个是仿真服务端负责物理步进、实体管理、插件调度、传感器数据生成另一个是图形客户端负责 3D 渲染和界面交互。这两者之间通过gz-transport通信消息走的是进程间通信机制而不是简单的函数调用。这种设计的直接好处是你可以只跑服务端完全不开启 GUI在服务器上做大规模并行仿真或者 CI 自动化测试。用gz sim -s可以指定只启动服务端模式后续其他进程再通过客户端连接。了解这一点很重要因为网上很多“黑屏”问题本质上不是仿真没跑而是客户端渲染挂了你用gz topic -l去看话题照样存在仿真数据照样在发只是窗口没显示出来。还有个参数值得留个心眼--server-port。默认情况下服务端用的是某个固定端口如果你在同一台机器上并发跑多个仿真实例端口冲突会直接导致启动失败。这时给不同实例指定不同端口就能隔离。提示刚上手时不要追求一模一样的截图效果先确认无头模式服务端模式也正常再回来鼓捣 GUI排查问题的维度会清晰很多。4.2 资源路径与模型加载在 Harmonic 里“世界”用 SDF 文件描述。SDF 是 Simulation Description Format 的缩写里面用 XML 结构定义物理参数、模型位置、光照、传感器等。我们在 3.4 节启动的shapes.sdf就是一个最简单的世界文件。如果你自己下载了网上的模型或世界文件想加载它路径配置是核心。Harmonic 会用自己的模型数据库目录存放 Fuel 在线仓库下载的模型也会通过环境变量GZ_SIM_RESOURCE_PATH指定额外的模型或世界搜索路径export GZ_SIM_RESOURCE_PATH$HOME/my_models:$HOME/my_worlds比如你有一个机器人模型放在~/robot_station/models/my_robot目录下面有model.config和对应的 SDF 文件那就把~/robot_station/models加进GZ_SIM_RESOURCE_PATH。否则即使你执行了gz sim my_world.sdfGazebo 也可能找不到模型给你一个红色感叹号或者干脆报资源不存在。SDF 文件的根结构通常长这样你可以把它当成一个后续手写世界的入门模板?xml version1.0? sdf version1.10 world namedefault light namesun typedirectional cast_shadowstrue/cast_shadows /light include urimodel://ground_plane/uri /include include urimodel://sun/uri /include /world /sdf这里model://前缀表示从模型库路径里找资源而不是从绝对路径加载。初学者最容易犯的错就是把uri写成相对路径或 Windows 风格路径导致 Gazebo 无法解析。4.3 插件系统与 ROS 2 桥接Harmonic 的功能扩展主要靠插件。整个仿真器的系统调度、传感器生成、物理引擎适配都是通过插件在 SDF 里声明的。举个例子如果要在世界里加一个差速驱动机器人模型SDF 里通常会有下面这样的插件块plugin filenamegz-sim-diff-drive-system namegz::sim::systems::DiffDrive left_jointleft_wheel_joint/left_joint right_jointright_wheel_joint/right_joint !-- 其他参数省略 -- /plugin插件以动态库形式加载文件名和系统名共同决定运行时的功能。刚开始用的时候不需要会自己写插件但至少要理解这种“以组件声明功能”的思路否则你拿到一个别人写的 world 文件会看不懂为什么有些模型能动、有些模型是死的。与 ROS 2 的联调是另一个重点。Harmonic 本身的话题并不属于 ROS 2它有自己的消息格式gz.msgs。要让 ROS 2 节点订阅或者发布 Gazebo 话题需要ros_gz_bridge这个桥接工具。典型用法是启动一个参数桥进程把 Gazebo 里的某个话题映射到 ROS 2 这边相同类型的话题ros2 run ros_gz_bridge parameter_bridge /cmd_velgeometry_msgs/msg/Twistgz.msgs.Twist命令里的三个部分分别表示输出的 ROS 2 话题、输出的 ROS 2 消息类型、输入的 Gz 消息类型。只有两边的消息结构对应上了数据才能正确流转。5. 常见问题与排查技巧实录5.1 版本混用启动的窗口不是 Harmonic不少用户装完才发现执行gz sim弹出来的界面或者终端日志显示的版本是 Fortress甚至更老。造成这个问题的主要原因就是没设置GZ_VERSIONharmonic。由于gz命令是多版本调度器它会按默认规则挑一个可用的版本如果系统上同时存在 Fortress 和 Harmonic它未必会选新的。排查时可以分两步走。先看系统里到底装了哪些 Gazebo 相关包dpkg -l | grep gazebo dpkg -l | grep gz-输出里如果同时有gz-sim6和gz-sim7那就要确认你当前的默认版本。然后强制指定环境变量export GZ_VERSIONharmonic gz sim --version如果你已经把 Harmonic 定为唯一使用版本可以直接把它写进~/.bashrc避免每次开终端都要手动设置。这个坑我在实际环境里碰到太多次了每次帮人排查第一句话就是问“你设了 GZ_VERSION 没有”。5.2 GPU 与渲染问题黑屏、闪退、无 GUI物理机上直接装通常没太大问题最头疼的是虚拟机和远程环境。常见的报错有qt.qpa.plugin: could not find the Qt platform plugin xcb这个属于 Qt 图形依赖缺失可以补装sudo apt install qtbase5-dev libqt5core5a libqt5gui5 libqt5widgets5还有一种情况是窗口能弹出来但内容全黑好像没有渲染任何物体。此时先查 OpenGL。没有 GPU 支持的虚拟机里OpenGL 的硬件加速基本不可用这时可以用软件渲染强制顶上去export LIBGL_ALWAYS_SOFTWARE1 gz sim -v4 -r shapes.sdf软件渲染性能会差不少但在没有显卡的环境里能保底跑通项目对调试逻辑来说足够了。如果你需要长期在服务器上跑仿真我建议直接走无头服务端模式只启服务端、不开 GUI把渲染负载降到最低。5.3 网络源问题apt update 失败与下载卡顿加完源后执行apt update如果提示The repository ... does not have a Release file或者NO_PUBKEY ...通常两个原因。第一种是发行版代号读取错误比如你手动了改$(lsb_release -cs)导致不是jammy第二种是密钥没有正确写到 keyrings 目录或者 keyrings 权限有问题。重新执行一遍 3.1 节的密钥下载命令再检查一下/etc/apt/sources.list.d/gazebo-stable.list里的内容多半能解决。下载模型卡顿是另一个高频问题。比如你加载某个 world 文件界面提示 Downloading model进度条半天不动原因通常是 Gazebo Fuel 在线模型仓库连接不稳定。我的建议是优先跑不依赖在线模型的示例先把环境和代码链路打通如果是自己项目里的模型就把模型文件整体放到本地并通过GZ_SIM_RESOURCE_PATH指过去。5.4 卸载与重新安装如果你中途装乱了想把环境彻底还原再重来最干净的方式是分三层清理。第一步卸载软件包sudo apt purge gazebo gz-sim7 -y sudo apt autoremove --purge -y第二步删除源文件sudo rm /etc/apt/sources.list.d/gazebo-stable.list sudo rm /usr/share/keyrings/pkgs-osrf-archive-keyring.gpg第三步确认没有残留dpkg -l | grep gz-清干净之后再按照第 3 章重新装这时候通常就正常了。不要在一个乱掉的环境里反复尝试操作清理重建往往比盲目调试更快。5.5 端口与多实例问题同一台机器上想跑多个仿真实例建议每个实例指定独立端口避免通信端口冲突。启动服务端时通过参数指定端口客户端再连接对应的端口。实际项目里我曾经在一台 32 核工作站上同时跑了 4 个无头仿真实例每个实例独立端口整体跑得很稳。这个经验说明 Harmonic 在这类并行需求上是靠谱的只是端口规划要好。6. 安装后的第一轮上手与进阶方向6.1 从 shapes 到自建世界第一次真正体验 Harmonicshapes.sdf只是验证环境能跑通的 Hello World。我建议你装好后接着做两件事。第一件加载一个稍微复杂一点的世界文件。可以先看看系统里还有哪些自带的 SDF 示例find /usr/share -name *.sdf 2/dev/null | head -20然后任选一个复杂点的 world 启动。如果它在加载时报模型下载超时就回到 4.2 节的资源路径配置。第二件学会在 GUI 里操作实体。Harmonic 的界面支持空格键启动/暂停仿真CtrlT 打开实体树在里面可以查看场景里的所有模型、组件和插件状态。当你以后做机器人调试实体树是定位模型是否成功加载、传感器是否生效的第一站。再进阶一点你可以尝试改shapes.sdf的副本给某个几何体加上物理属性、改变位置然后重新加载看看反馈。这个过程中你会逐渐理解 SDF 中model、link、collision、inertial这几个核心标签的关系这也是之后做机器人模型导入的基础。6.2 与 ROS 2 打通的最小闭环如果你要往 ROS 2 方向发展打通闭环很重要。假设你已经装好 ROS 2 Humble 并有ros_gz桥接包那么可以这样跑一个最小闭环先启动一个包含差速驱动机器人的仿真世界确认gz topic -l能看到/cmd_vel这样的话题然后启动参数桥ros2 run ros_gz_bridge parameter_bridge /cmd_velgeometry_msgs/msg/Twistgz.msgs.Twist在 ROS 2 侧发布一个速度指令如果你能在 Gazebo 里看到机器人开始移动说明整个链路已经通了。这是所有基于仿真的机器人开发项目最基础、也最关键的一步验证。之后再接激光雷达、IMU、相机无非就是多配几组话题映射而已。6.3 从装好到用好我的几条经验最后再说几个我自己的习惯算是长期踩坑之后的收尾建议。第一环境变量一定固化。不要每次开终端手敲export GZ_VERSIONharmonic写进~/.bashrc是最低成本的保险。第二模型资源路径规划好。把所有项目模型放到一个统一目录按models和worlds分好类再在配置里一次性把GZ_SIM_RESOURCE_PATH指完整不要等到加载失败才回头找。第三遇到窗口显示问题先不要急着卸载重装先尝试软件渲染模式或者改用无头模式验证服务端是否正常。很多时候你以为环境坏了其实只是渲染栈缺了某个 Qt 锅和 OpenGL 库而已。希望这些经验能让你在 Ubuntu 22.04 上装 Gazebo Harmonic 的过程少一些折腾多一些摸到仿真器的踏实感。