★ FEATURED ARTICLE Ubuntu 22.04 上装 Gazebo Harmonic看起来只是几条 apt 命令的事但实际坑不少版本命名搞得人头晕、旧环境没清干净导致装上打不开、显卡驱动不行直接黑屏甚至装完gz命令都找不到。这篇文章我按自己的实操流程整理一遍把版本搞清楚、环境清理、官方源安装、首次启动和踩坑排查都讲仔细适合刚接触新一代 Gazebo、之前主要玩 Classic 的读者参考。1. 为什么要装 Harmonic新一代 Gazebo 的版本谱系1.1 从 Classic 到 Harmonic 的换名史很多刚从 Gazebo Classic 迁移过来的朋友第一次看到 Gazebo Harmonic 都会愣一下Harmonic 是什么和 Classic 什么关系这里得先理一理命名。老一代的 Gazebo 通常叫 Gazebo Classic比如你以前装过的gazebo11。从 2019 年左右开始官方实际上推出了一套完全重写的新架构早期叫 Ignition Gazebo。从 Garden 版本开始官方把 Ignition 前缀去掉了直接叫 Gazebo于是新一代 Gazebo 的版本号就延续成了 Harmonic。所以你现在看到的 Gazebo Harmonic本质上就是新一代 Gazebo 的一个长期支持版本对应的库版本是gz-sim8和 Classic 那套东西不是一个代码体系。1.2 Harmonic 和 Ubuntu 22.04 为什么是绝配Harmonic 是官方钦定的长期支持LTS版本官方安装文档里首选的系统就是 Ubuntu 22.04 Jammy。这意味着你在 22.04 上装 Harmonic绝大部分依赖都已经有现成的二进制包不用自己编译。相比 Fortress 主要面向 20.04Garden 又是非 LTS 的短命版本Harmonic 对 22.04 用户来说就是最稳妥的选择。它的定位其实很明确稳定的 API、持续维护的 Bug 修复、以及一套以插件化系统为核心的仿真引擎。如果你打算长期做机器人仿真或者要配合 ROS 2 Humble 做开发Harmonic 就是当前最合理的落脚点。1.3 什么时候不该装 Harmonic不是所有人都需要立刻上 Harmonic我见过不少装完又后悔的你的机器人算法包、仿真插件只适配 Gazebo Classic尤其是还在用 ROS 1 的老项目。你用的机器人仿真教程全部基于 Classic 的gazebo_ros_pkgs迁移到新架构需要改不少代码。你的机器是 Ubuntu 20.04那就应该装 Fortress 而不是 Harmonic硬装在 20.04 上会遇到一堆依赖不满足的问题。所以先想清楚你需要的是新旧仿真引擎哪个。确定之后再往下走环境准备。2. 安装前的系统体检这一步偷懒后面全是坑2.1 确认系统版本和一些基础工具安装前先确认系统确实没问题cat /etc/os-release重点看VERSION_CODENAME是不是jammy。某些精简版系统连lsb_release都没有所以下面用到lsb_release -cs之前建议先补上基础工具sudo apt update sudo apt install -y curl lsb-release ca-certificates另外看下磁盘空间不要最后安装时发现根分区被占满了df -h /Harmonic 本体加上依赖大概占几个 GB磁盘不足 10GB 就有点悬了。2.2 清理旧的 gazebo、ignition 残留包这一步最容易忽略。之前装过gazebo11或者折腾过ignition-fortress的朋友不要直接开始装 Harmonic新旧包混在一起极容易出现gz命令冲突、库版本错乱的问题。建议先做一次大扫除sudo apt remove gazebo* libgazebo* ignition-* -y sudo apt autoremove --purge -y同时检查一下/etc/apt/sources.list.d/下是否有旧的 gazebo 源文件ls /etc/apt/sources.list.d/如果有类似gazebo-stable.list的旧内容先删掉或者注释掉避免后面 apt update 的时候出现 404、公钥报错。2.3 检查 OpenGL 支持决定你能不能看到仿真窗口很多人装完 Harmonic启动后只有黑窗口十有八九是 OpenGL 版本太老。Harmonic 的默认渲染引擎是 Ogre 2至少需要 OpenGL 3.3 以上。先安装检测工具并确认sudo apt install -y mesa-utils glxinfo -B | grep OpenGL renderer如果输出里出现llvmpipe说明你现在走的是 CPU 软件渲染运行起来会非常卡而且容易黑屏。这时候要么安装对应显卡驱动要么在虚拟机里开启 3D 加速。检测工具暂时装不了也没关系后面我会给一个软件渲染的兜底方案。提示这个 OpenGL 检查不要跳过。我在几台机器上反复踩过同一个坑装完包一看界面根本渲染不出来全部倒在这一步。3. 使用官方 APT 源安装 gz-harmonic 的完整命令3.1 添加 GPG 密钥和软件源的正确姿势新版官方文档推荐的方式是把密钥文件放到/usr/share/keyrings/然后在源描述里用signed-by指定它。不要再用老的apt-key add那个方式已经过时而且会在系统里留下全局信任的密钥。执行如下命令curl -sSL https://packages.osrfoundation.org/gazebo.gpg -o /tmp/gazebo.gpg sudo install -Dm644 /tmp/gazebo.gpg /usr/share/keyrings/pkgs-osrf-archive-keyring.gpg 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 /dev/null这里的印章是固定的可以检查一下cat /etc/apt/sources.list.d/gazebo-stable.list输出内容里$(lsb_release -cs)应该被替换成了jammy。如果你的系统里lsb_release不可用手动把仓库源地址里的那一段写成jammy即可。3.2 安装 gz-harmonic 并验证版本源添加好后更新索引并安装sudo apt update sudo apt install -y gz-harmonic安装包的时候可以看到会拉进来一堆libgz-*、sdformat、ogre等相关依赖这属于正常现象因为gz-harmonic是一个元包它会把整个仿真平台组件都带进来。装完先不要急着启动 GUI先做版本验证source /usr/share/gz/setup.sh gz sim --version如果能看到类似Gazebo Simulation version 8.x.x的输出就说明安装成功了。gz sim --version是判断装没装对最快的方式比去菜单里找图标靠谱得多。3.3 环境变量配置为了让每次打开终端都能直接使用gz命令建议把这个 source 写进 bashrcecho source /usr/share/gz/setup.sh ~/.bashrc source ~/.bashrc如果你以后要经常加载自定义模型和世界再加一个资源路径变量echo export GZ_SIM_RESOURCE_PATH${GZ_SIM_RESOURCE_PATH}:$HOME/gazebo_models:/usr/share/gz/gz-sim8/worlds ~/.bashrc source ~/.bashrc3.4 关于 ROS 2 Humble 的集成说明如果你后续要再接 ROS 2 Humble可以关注ros_gz_bridge这一类的桥梁包。不过要注意ROS 2 官方 apt 源里的ros-humble-ros-gz不一定匹配 Harmonic很多时候需要自己按文档编译对应分支。所以在一开始装完 Harmonic 之后先别急着apt installROS 侧的仿真桥接包先搞清楚你需要的 ROS 版本和 Gazebo 版本再去官方仓库查对应分支能少踩一个大坑。4. 第一次启动从加载世界到 GUI 操作4.1 启动默认世界验证通过后直接启动一个内置的 shapes 世界gz sim shapes.sdf第一次启动会加载渲染引擎慢一点是正常的。看到 GUI 窗口出来后可以按播放按钮或者直接空格你会看到一堆立方体、球体从空中掉下来。这一步能跑通说明你的机器渲染环境和核心插件都正常。内置世界不止 shapes 一个可以列出看看ls /usr/share/gz/gz-sim8/worlds/里面通常有empty.sdf、shapes.sdf、camera_sensor.sdf、rgbd_camera.sdf这些够你入门把所有传感器玩一遍。4.2 视角操作和基本交互Harmonic 的 GUI 操作和 Classic 不太一样新手经常卡在视角上。核心操作如下鼠标左键拖拽旋转视角鼠标滚轮缩放鼠标中键或右键拖拽平移视角点击模型选中对象右侧属性面板可以看位置、姿态、速度等信息左侧边栏的 Spawn 面板可以把模型拖进世界如果你玩过 3D 编辑器这套操作基本是肌肉记忆。关键是把视角转顺畅后面放置模型、看传感器数据才会有体感。4.3 无显示器、无独立显卡时的启动方式很多时候我们的 Ubuntu 22.04 是台服务器或者一台没有桌面环境的机器这时候不能直接弹 GUI。Harmonic 本身是典型的客户端-服务端架构可以只启动服务端gz sim -s -v 4 empty.sdf另开一个终端再启动 GUI 客户端去连接gz sim -g -v 4这样服务端在后台跑仿真逻辑GUI 可以只在你需要的时候连上去看。如果连服务端也不需要真的渲染只想让传感器能出图可以加--headless-rendering参数。远程开发场景下这个组合非常好用。如果本机没有任何 GPU 支持但仍然想看 GUI可以用软件渲染兜底LIBGL_ALWAYS_SOFTWARE1 gz sim shapes.sdf不过说实话软件渲染性能和体验都一般只能用于确认环境没问题真要跑仿真还是建议上正常显卡驱动。5. 装完容易踩的坑按现象排查不绕弯子5.1 apt update 报 404 或公钥失效原因通常是之前残留了旧的 Gazebo 源配置或者把系统版本代号搞错了。排查顺序grep -rn packages.osrfoundation /etc/apt/sources.list.d/确认里面只有gazebo-stable.list一个文件且内容正确。公钥的问题就用第 3 节里的signed-by方式重新装密钥。不要用apt-key add来掩盖问题它只是把问题延后了。5.2 启动后黑屏、渲染器崩掉这是我在踩坑统计里见过最多的现象。核心原因就是 OpenGL 版本不够。先用第 2 节的glxinfo -B确认渲染器是不是llvmpipe如果是优先装显卡驱动在虚拟机里则开启 3D 加速。临时顶上来的方案就是软渲染LIBGL_ALWAYS_SOFTWARE1 gz sim -v 4 empty.sdf如果软渲染也只能看到一片黑检查日志里有没有Failed to load plugin字样把当时的完整输出发出来排查会更快。5.3 gz 命令找不到或者版本不对装完输入gz sim --version报 command not found大概率是没 source 环境文件。先手动执行一次source /usr/share/gz/setup.sh gz sim --version如果这样没问题就把 source 写进 bashrc 一劳永逸。如果提示版本是 7.x 或者更老说明你机器上装了 Garden 或别的版本检查一下安装历史dpkg -l | grep gz-sim再把不需要的版本卸载干净重装。5.4 插件加载失败启动时报Failed to load library ...gz-sim-8/plugins/...常见原因有安装了 32 位包和系统架构不匹配GZ_SIM_SYSTEM_PLUGIN_PATH环境变量被改成奇怪路径卸载残留导致部分插件文件缺失直接重装解决sudo apt install --reinstall gz-harmonic再手动确认插件目录存在ls /usr/lib/x86_64-linux-gnu/gz-sim-8/plugins/5.5 常见问题快速对照表现象主要原因处理手段apt update 报 404源文件里系统代号错误检查gazebo-stable.list改为 jammy公钥校验失败密钥没放到 keyrings 目录重新下载 gpg用signed-by方式GUI 黑屏OpenGL 低于 3.3装驱动或开启虚拟机 3D 加速gz找不到命令未 source setup.sh执行source /usr/share/gz/setup.sh插件加载失败插件路径不对或包损坏重装 gz-harmonic检查插件目录启动极卡软件渲染安装正常显卡驱动端口冲突多个 gazebo 实例先停掉旧进程再启动6. 安装完值得立刻试的几个小实验6.1 用 shapes.sdf 验证物理引擎启动gz sim shapes.sdf后点播放按钮观察物体下落、碰撞、堆叠。这一步能同时验证物理引擎、渲染引擎、默认插件是否正常。把视角转到底部还能看到地面网格。如果想体验传感器再试试gz sim camera_sensor.sdf运行起来后可以在 GUI 里切到 camera 视角实时看到画面这就是将来做视觉仿真的基础。6.2 用命令行方式加载模型不一定要全程用 GUI 拖模型。Harmonic 支持通过命令行主动描述生成模型比如gz model --spawn-file ~/my_robot.sdf --name my_robot -x 1 -y 0 -z 0.1看到模型出现在世界中就说明命令行加载路径没问题。具体参数可以随时用gz model --help查看。对于自动化测试和批量跑场景来说命令行方式是必须掌握的。6.3 保存你的世界文件在 GUI 里调整完模型位置后可以通过界面菜单把当前世界保存成 SDF 文件。这样下次启动时直接gz sim /path/to/my_world.sdf就能恢复到上次的状态。保存出来的 SDF 文件是纯文本可以用文本编辑器打开你会发现里面就是实体、灯光、物理属性的结构化描述这也是 Gazebo 和 Classic 在设计理念上一个很大的不同一切皆可配置一切皆可脚本化。写在最后装 Harmonic 这件事本身不难难的是把环境概念理清楚它和 Classic 不是同一个东西Ubuntu 22.04 有官方直接支持的包安装走的是 keyrings 加 apt 源这套现代流程而不是 Google 搜索里那些老博客的apt-key add。我每次重装环境都会先跑一遍版本检查再清旧包再装 gz-harmonic最后用gz sim --version和gz sim shapes.sdf两次验证。这套流程走到现在基本没有翻过车。如果你装的过程中卡在某个具体报错建议先把完整日志贴到本地保存然后对照第 5 节的排查表一项一项过少走弯路。
阅读完成 · 觉得有帮助？
