实战从零把一个package发布成 ROS2 官方包

对于普通 ROS2 用户来说，很多软件包的常规使用方式仍然是：先克隆源码，再安装依赖，最后在自己的工作空间中编译。只有被 ROS 官方收录，并且经过构建农场编译、同步到官方 apt 源之后，用户才能用类似 sudo apt install ros-humble-* 的方式直接安装二进制包。

这篇文章以我发布 FastSwarmSim 的5个包到ROS2 官方apt源为例，记录一个 ROS 项目如何从源码仓库走到 ROS 官方 apt 源，以及每个阶段大致花了多长时间。

一点吐槽

发布FastSwarmSim到ROS官方apt的整个过程从 2026 年 8 月中旬开始，到 9 月中旬完成 release repository 和 Bloom 发布准备，前后已经接近一个月 ；后面还要继续等待 rosdistro 合并、构建农场编译和 apt 源同步。对个人开发者来说，这个周期和门槛都不算低。

我觉得ROS 官方发布二进制包的流程，比 PyPI 发布一个 Python 包要麻烦得多。PyPI 通常是准备好包、构建 wheel、检查元数据，然后上传即可；而 ROS 还需要经历发行版索引、release team、release repository、Bloom、rosdistro 和构建农场等多个环节。整个过程可能持续数月，任何一个环节等待维护者处理，发布就会停在那里。

但这套繁琐流程也有积极的一面。它会在发布过程中筛掉相当一部分没有维护意愿、包结构不完整、依赖关系混乱或质量不稳定的项目。能够进入官方 apt 源的包，至少经过了命名、元数据、依赖、构建和发行版集成等多层检查，这对 ROS 生态的稳定性是有价值的。

问题在于，目前这套质量保障机制的门槛和时间成本都太高，很多本来可以使用的 ROS 包，可能因为发布流程过于复杂而长期停留在源码仓库阶段。我的看法是，ROS 官方未来可以在不降低质量检查的前提下，进一步自动化 release team、release repository、Bloom 和构建状态管理，提供更清晰的进度反馈和更低门槛的发布入口。

1. 为什么要把项目发布成 ROS 官方包？

FastSwarmSim 是一个面向 PX4 兼容多旋翼和多无人机算法开发的轻量级 ROS 2 仿真器。它把精简后的 PX4 运行时、MAVROS 兼容接口、本地点云仿真、RViz 可视化和锁步仿真时间组织在一起，主要用于多无人机算法验证、可重复的仿真实验和大规模集群原型开发。

在项目早期，用户需要先克隆源码，再运行 rosdep 安装依赖，最后使用 colcon build 编译。源码安装对开发者是必要的，但对普通使用者来说，步骤比较长，也容易受到系统环境、依赖版本和网络状况影响。

所以我希望最终达到一个更直接的状态：用户只需要执行一条 apt install 命令，就可以把 FastSwarmSim 的全部 ROS 包安装下来。

2. 第一个阶段：先进入 ROS Index

ROS 官方发布不是把代码上传到某个软件包网站这么简单。第一步，需要先把源码仓库加入目标 ROS 发行版的 distribution.yaml，让 ROS 系统知道这个项目的源码位置、分支和维护状态。

我先向 ros/rosdistro 提交了 ros/rosdistro#53487，目标是把 FastSwarmSim 的源码仓库加入 ROS 2 Humble 的索引。

这个 PR 有一个容易被忽略的要求：第一次提交时，只添加 source 和 status，不要提前添加 release 字段。也就是说，这一步只是告诉 ROS：

FastSwarmSim 的源码在哪里，有哪些包，当前由谁维护。

它还不代表包已经进入 ROS 构建农场，更不能说明此时已经可以通过 apt 安装。

这个 PR 中列出了 FastSwarmSim 的 5 个包，并明确仓库地址为 https://github.com/shupx/FastSwarmSim.git，源码分支为 main。自动检查还发现了 YAML 字母顺序问题，我根据机器人检查结果调整了条目位置，最终 PR 合并。

从提交到合并，这个阶段大约用了 5 天：

提交时间：2026 年 8 月 25 日；
合并时间：2026 年 8 月 30 日；
结果：FastSwarmSim 出现在 ROS Index 中，但当时仍未完成二进制发布。

3. 第二个阶段：申请 release team 和 release repository

源码进入 ROS Index 之后，还需要为项目准备 release team 和 release repository。这里涉及 ros2-gbp 组织，也就是 ROS 2 Debian 包发布流程中负责维护 release 仓库的一部分基础设施。

我创建了 ros2-gbp/ros2-gbp-github-org#1110，申请创建 fastswarmsim release team，并把自己的 GitHub 账号加入团队。

这个阶段并不是简单地新建一个空仓库。维护者需要先确认：

源码仓库已经通过 rosdistro 的源码索引和包名检查；
项目包含哪些 ROS 包；
是否已经存在可以导入的 release 仓库；
申请人是否需要被授予对应的维护权限。

在等待过程中，维护者先指出源码仓库必须完成 rosdistro 索引。等 #53487 合并后，才继续推进 release team 的创建。之后，维护者通过 ros2-gbp/ros2-gbp-github-org#1144 完成了 fastswarmsim 团队的创建，并部署了 fastswarmsim-release 仓库。

从最初提交 release team Issue 到 release repository 部署完成，大约用了 30 天：

Issue 创建时间：2026 年 8 月 19 日；
release team 部署完成：2026 年 9 月 18 日；
中间主要是等待 rosdistro 源码索引通过，以及 ROS 维护者完成团队和仓库配置。

这也是整个过程中等待时间最长的一段。代码本身可能只需要几个命令，但进入官方基础设施之后，每一步都要等对应维护者确认。到这里，整个流程已经明显比在 PyPI 发布一个 Python 包繁琐得多。

4. 第三个阶段：Bloom release 和 rosdistro 二进制发布 PR

release repository 准备好之后，才进入真正的 Bloom 发布阶段。

按照 FastSwarmSim 的发布说明，需要在源码仓库中完成依赖检查、版本准备和 Bloom release。Bloom 会完成几件事：

给源码仓库打上新的版本标签；
在 fastswarmsim-release 中生成对应的 release 分支；
根据源码版本和 release 仓库内容，自动生成 rosdistro 的 release 条目；
向 ros/rosdistro 提交新的发布 PR。

这里最容易遇到的问题，是 rosdep 镜像或索引地址导致 Bloom 没有顺利生成 rosdistro PR。我的处理方式是把 ROSDISTRO_INDEX_URL 明确指向官方 index-v4.yaml，必要时只重新执行生成 PR 的步骤，而不是重复整个 release 流程。

最终，Bloom 生成了 ros/rosdistro#54047，目标是在 ROS 2 Humble 的 distribution.yaml 中加入 fastswarmsim 的 0.1.2-1 release 信息。

这个 PR 里已经能看到 5 个包的发布信息：

fss_bringup；
fss_px4_sim；
fss_sensing；
fss_time；
fss_time_interfaces。

从 release repository 部署到 Bloom 生成这个 PR，基本是同一天完成的。这个阶段的人工操作时间并不长，真正需要注意的是版本号、源码仓库、release 仓库、ROS 发行版和分支名称必须全部对应。

5. 最终结果：从源码构建变成 apt 安装

发布流程的最后一步，是等待 rosdistro release PR 合并，并等待 ROS 构建农场完成 Debian 包构建和同步。

FastSwarmSim 的 release repository 已经记录了 Humble 版本 0.1.2-1，并列出了这 5 个待进入 Humble 二进制分发链路的 ROS 包。当对应 release 信息完成 rosdistro 合并，并同步到 ROS 2 Humble 的 apt 源之后，用户就可以直接执行下面的命令。若刚完成合并时仍提示找不到软件包，通常需要等待构建农场和 apt 源同步完成。

bash 复制代码

sudo apt update
sudo apt install \
  ros-humble-fss-bringup \
  ros-humble-fss-px4-sim \
  ros-humble-fss-sensing \
  ros-humble-fss-time \
  ros-humble-fss-time-interfaces

相比源码安装，这种方式的变化很明显：

不需要手动克隆 FastSwarmSim；
不需要自己调用 rosdep install；
不需要本地执行 colcon build；
不需要维护源码工作空间；
可以直接复用 ROS 的版本和依赖管理机制。

安装完成后，仍然需要根据使用的终端加载 ROS 2 Humble 环境。例如，运行仿真前先加载 /opt/ros/humble/setup.bash，然后就可以直接使用 fss_time、fss_px4_sim、fss_sensing 和 fss_bringup 提供的功能。

从源码仓库到 ROS 官方二进制包，真正困难的地方并不只是"把程序编译出来"，而是要把源码索引、包名规范、release team、release repository、Bloom、rosdistro 和构建农场这一整条链路接通。

开源项目的发布，不只是写完代码和打一个 Git tag。只有当别人能够用标准方式找到、安装和升级它，项目才真正从"我的仓库"变成了"生态中的一个软件包"。