1. 从零发布一个 ROS2 官方包，到底在做什么
很多人第一次听到“把自己的代码发布成 ROS2 官方包”，脑子里浮现的可能是往某个中心仓库上传一个压缩包，然后等审核通过就完事了。实际完全不是这么回事。ROS2 的包管理体系建立在ament和colcon这套构建工具链之上，而“官方包”通常指的是能够进入 ROS 官方软件源、被全球开发者通过apt或rosdep直接安装的包。这意味着你的包不仅要能编译、能跑，还要满足一整套命名规范、依赖声明、版本管理、许可证和构建配置的要求。
我自己第一次尝试把内部工具包推成官方可用的形态时，踩的坑从package.xml格式错误到CMakeLists.txt里install规则缺失，前后折腾了将近两周。所以这篇内容我会把整个流程拆开，从目录结构设计、构建系统选择、依赖声明、测试验证，一直到提交到官方索引仓库的完整链路，全部讲清楚。适合已经写过 ROS2 节点、但还没走过完整发布流程的开发者，也适合想把自己封装的算法模块或驱动包开放出去的团队参考。
核心要解决的问题有三个：第一，让你的包在任何一台装了 ROS2 的机器上都能被正确找到和编译；第二，让包的元信息足够规范，能被rosdep、colcon、rosdistro这些工具识别；第三，通过官方索引的审核，进入rosdistro的发行版列表。下面我按实际操作的顺序，一层层往下拆。
2. 发布前的整体设计与关键决策
2.1 先搞清楚“官方包”的两种含义
在 ROS2 生态里，“官方包”其实有两种不同的落地形态，很多人一开始就混淆了，导致后面走弯路。
第一种是进入ROS Index 和 rosdistro 官方发行列表，也就是你在index.ros.org上能搜到、并且可以通过apt install ros-humble-xxx直接安装的包。这类包需要提交到rosdistro仓库，经过维护者审核后合入对应的发行版文件。第二种是发布到ROS 官方的包索引但托管在你自己的仓库，也就是源码仓库还是你自己的，只是把元信息登记到官方索引里，方便别人通过rosdep解析依赖。
我建议新手先从第二种形态入手，因为它的审核门槛相对低，流程也更可控。等你对package.xml、bloom发布流程、rosdistro的 PR 机制熟悉之后，再考虑进入官方软件源。这个顺序很重要，直接冲第一种很容易在审核环节被反复打回，消耗大量时间。
2.2 构建系统选型：ament_cmake 还是 ament_python
ROS2 的包构建系统主要分两类：ament_cmake和ament_python。选哪个不是看个人喜好，而是看你的包里面到底有什么。
如果你的包包含 C++ 节点、需要编译的库、或者要导出 CMake 配置文件给其他包使用，那必须用ament_cmake。如果你的包纯粹是 Python 脚本、节点逻辑用rclpy写、没有编译产物，那ament_python更轻量，配置也更简单。
我见过有人用ament_cmake去包一个纯 Python 的包，结果CMakeLists.txt写了一百多行，全是install规则，维护起来非常痛苦。反过来，用ament_python去包一个带 C++ 扩展的包，编译直接失败。所以这个决策要在动手写代码之前就定下来。
| 构建类型 | 适用场景 | 配置文件 | 编译产物 |
|---|---|---|---|
| ament_cmake | C++ 节点、库、消息定义 | CMakeLists.txt + package.xml | 可执行文件、共享库 |
| ament_python | 纯 Python 节点、工具脚本 | setup.py + package.xml | Python 模块 |
| 混合型 | Python 节点 + C++ 库 | 两者都要 | 两者都有 |
混合型包是最麻烦的，需要同时维护CMakeLists.txt和setup.py，而且install规则要写两套。如果不是必须，尽量拆成两个包，一个 C++ 库包，一个 Python 节点包，通过依赖关系关联。
2.3 包命名与版本号的硬性约束
ROS2 对包名有明确要求：全小写、只能用字母数字和下划线、不能以数字开头、不能和已有包重名。我当初想用一个带大写的名字，结果colcon build直接报错，排查了半天才发现是命名规范问题。
版本号遵循语义化版本规范，格式是MAJOR.MINOR.PATCH。官方索引对版本号有额外要求：首次发布建议从0.1.0开始，不要一上来就1.0.0，因为1.0.0通常意味着 API 已经稳定，而官方审核会关注这一点。如果你的包还在快速迭代，用0.x.y更合适。
注意：包名一旦发布到官方索引，后续修改成本极高，因为所有依赖它的包都会受影响。所以在定名字之前，先去
index.ros.org搜一遍，确认没有冲突。
3. 包结构搭建与核心文件配置
3.1 标准目录结构长什么样
一个规范的 ROS2 包，目录结构不是随便摆的。以ament_cmake为例，我实际用的结构是这样的：
my_awesome_pkg/ ├── CMakeLists.txt ├── package.xml ├── include/ │ └── my_awesome_pkg/ │ └── visibility_control.h ├── src/ │ └── my_node.cpp ├── launch/ │ └── my_node.launch.py ├── config/ │ └── params.yaml ├── test/ │ ├── test_my_node.cpp │ └── test_copyright.py ├── LICENSE ├── README.md └── CHANGELOG.rstinclude目录下放头文件，src放源文件，launch放启动文件，config放参数配置，test放测试代码。LICENSE和README.md是官方审核必查项，CHANGELOG.rst虽然不是强制，但强烈建议加上，因为bloom发布时会用到。
对于ament_python的包，结构略有不同：
my_python_pkg/ ├── package.xml ├── setup.py ├── setup.cfg ├── resource/ │ └── my_python_pkg ├── my_python_pkg/ │ ├── __init__.py │ └── my_node.py ├── launch/ ├── test/ ├── LICENSE └── README.md注意resource目录下要放一个和包同名的空文件，这是ament_python用来标记包位置的，少了它ros2 run会找不到包。
3.2 package.xml 的每一行都不能马虎
package.xml是整个包的身份证，官方审核第一眼看的就是它。我当初因为<license>标签写了个不规范的字符串，被审核者要求重写。下面是一个完整的模板：
<?xml version="1.0"?> <?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?> <package format="3"> <name>my_awesome_pkg</name> <version>0.1.0</version> <description>A brief description of what this package does.</description> <maintainer email="you@example.com">Your Name</maintainer> <license>Apache-2.0</license> <buildtool_depend>ament_cmake</buildtool_depend> <depend>rclcpp</depend> <depend>std_msgs</depend> <test_depend>ament_lint_auto</test_depend> <test_depend>ament_lint_common</test_depend> <export> <build_type>ament_cmake</build_type> </export> </package>几个关键点：format="3"是当前推荐版本，<license>必须用 SPDX 标准标识符，比如Apache-2.0、MIT、BSD-3-Clause。<maintainer>的邮箱必须真实有效，官方审核会验证。<export>里的<build_type>决定了colcon用哪种构建方式。
提示：
<depend>标签会自动展开为<build_depend>、<build_export_depend>和<exec_depend>。如果你的依赖只在编译时需要，用<build_depend>；只在运行时需要，用<exec_depend>。不要图省事全用<depend>，官方审核会关注依赖声明的精确性。
3.3 CMakeLists.txt 的 install 规则是重灾区
ament_cmake的CMakeLists.txt里，最容易出问题的就是install规则。很多人本地colcon build能过，但别人装完之后ros2 run找不到节点，原因就是可执行文件没有正确安装。
cmake_minimum_required(VERSION 3.8) project(my_awesome_pkg) if(CMAKE_COMPILER_IS_GNUCXX OR CMAKE_CXX_COMPILER_ID MATCHES "Clang") add_compile_options(-Wall -Wextra -Wpedantic) endif() find_package(ament_cmake REQUIRED) find_package(rclcpp REQUIRED) find_package(std_msgs REQUIRED) add_executable(my_node src/my_node.cpp) ament_target_dependencies(my_node rclcpp std_msgs) install(TARGETS my_node DESTINATION lib/${PROJECT_NAME} ) install(DIRECTORY launch config DESTINATION share/${PROJECT_NAME} ) if(BUILD_TESTING) find_package(ament_lint_auto REQUIRED) ament_lint_auto_find_test_dependencies() endif() ament_package()install(TARGETS ... DESTINATION lib/${PROJECT_NAME})这一行决定了ros2 run my_awesome_pkg my_node能不能找到可执行文件。install(DIRECTORY ...)负责把launch和config目录复制到安装空间。ament_package()必须放在最后，它负责生成包的元信息。
我踩过的一个坑是：launch目录如果不存在，install(DIRECTORY launch ...)会直接报错。所以要么确保目录存在，要么用OPTIONAL参数。这种细节在本地开发时不容易发现，但官方审核的 CI 会直接跑失败。
4. 完整实操流程与关键环节
4.1 从零创建包并跑通本地构建
假设你已经装好了 ROS2 Humble，工作空间在~/ros2_ws。第一步是创建包：
cd ~/ros2_ws/src ros2 pkg create --build-type ament_cmake my_awesome_pkg \ --dependencies rclcpp std_msgs \ --node-name my_node这条命令会自动生成package.xml、CMakeLists.txt和src/my_node.cpp的骨架。但自动生成的package.xml里<license>是空的，<description>也是占位符，这些都要手动补全。
然后写一个最简单的节点，编译验证：
cd ~/ros2_ws colcon build --packages-select my_awesome_pkg source install/setup.bash ros2 run my_awesome_pkg my_node如果这一步能跑起来，说明基础结构没问题。接下来才是真正麻烦的部分：补全所有元信息、加测试、加文档、配置 lint。
4.2 依赖声明的精确化处理
rosdep是 ROS2 用来解析系统依赖的工具。你的package.xml里声明的依赖，必须能被rosdep正确解析。我遇到过的情况是：本地装了某个库，编译能过，但rosdep install在别人的机器上找不到对应的系统包。
排查方法是：
rosdep resolve rclcpp rosdep resolve std_msgs如果某个依赖rosdep解析不出来，说明它不在rosdistro的依赖映射表里。这时候要么换一个等价的、能被解析的依赖，要么在包的README里明确说明需要手动安装。
对于第三方库依赖，比如Eigen3、OpenCV，在package.xml里用<depend>eigen</depend>这种形式，rosdep会自动映射到系统包。但如果你用了一个很小众的库，rosdep不认识，那就需要在rosdistro里提 PR 添加映射，或者干脆把这个库的源码一起打包进你的包。
注意：官方审核对依赖的“可解析性”要求很严。如果你的包依赖了一个
rosdep无法解析的库，审核基本不会通过。所以在提交之前，务必用rosdep check跑一遍。
4.3 测试与 lint 配置
官方包必须包含基本的测试。ament_lint_auto和ament_lint_common提供了一套标准的代码检查规则，包括版权头检查、格式检查、拼写检查等。在package.xml里加上：
<test_depend>ament_lint_auto</test_depend> <test_depend>ament_lint_common</test_depend>然后在CMakeLists.txt里加上前面提到的BUILD_TESTING块。跑测试：
colcon test --packages-select my_awesome_pkg colcon test-result --verboseament_lint_common里的copyright检查会扫描每个源文件，要求文件头有版权声明。格式通常是：
// Copyright 2024 Your Name // // Licensed under the Apache License, Version 2.0 (the "License"); // ...这个检查非常严格，少一行都不行。我当初因为一个测试文件忘了加版权头，CI 直接红了。建议在写第一个文件的时候就把模板建好，后面复制粘贴。
4.4 生成 CHANGELOG 和文档
CHANGELOG.rst是bloom发布时用来生成发行说明的。格式遵循catkin的 changelog 规范：
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Changelog for package my_awesome_pkg ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 0.1.0 (2024-01-15) ------------------ * Initial release * Added basic node functionalityREADME.md要包含：包的功能说明、安装方法、使用示例、依赖要求、许可证信息。官方审核会看README来判断这个包是否“对社区有价值”。如果README只有一行字，大概率被打回。
4.5 提交到 rosdistro 的完整流程
当你确认包本身没问题之后，就可以走官方发布流程了。核心工具是bloom，但在此之前需要先把包的信息登记到rosdistro。
第一步，在 GitHub 上 forkrosdistro仓库。第二步，在humble/distribution.yaml里添加你的包条目：
my_awesome_pkg: source: type: git url: https://github.com/yourname/my_awesome_pkg.git version: main status: developed第三步，提 PR。审核者会检查你的仓库是否有package.xml、是否有LICENSE、是否有基本的测试。通过之后，你的包就会出现在index.ros.org上。
第四步，用bloom生成发行仓库：
bloom-generate rosdebian --os-name ubuntu --os-version jammy --ros-distro humble这一步会生成debian目录和rules文件。然后fakeroot debian/rules binary构建 deb 包。如果这一步能过，说明你的包已经具备了进入官方软件源的条件。
我实际走这个流程的时候，卡在bloom的版本号解析上。bloom要求package.xml里的版本号和CHANGELOG.rst里的版本号一致，而且CHANGELOG的格式必须严格符合规范。差一个空格都会报错。
5. 常见问题与排查技巧实录
5.1 colcon build 报 “package not found”
这是最高频的问题。原因通常有三种：包不在src目录下、package.xml格式错误、或者COLCON_IGNORE文件存在。
排查顺序：先确认src目录下有package.xml，然后跑colcon list看包是否被识别。如果colcon list里没有，检查package.xml的 XML 格式，用xmllint验证：
xmllint --noout package.xml如果格式没问题但还是找不到，检查目录里有没有COLCON_IGNORE文件，这个文件会让colcon跳过整个目录。
5.2 ros2 run 找不到节点
编译成功但运行时报No executable found，九成是install规则没写对。检查CMakeLists.txt里有没有install(TARGETS ... DESTINATION lib/${PROJECT_NAME})。对于 Python 包，检查setup.py里的entry_points配置：
entry_points={ 'console_scripts': [ 'my_node = my_python_pkg.my_node:main', ], },还有一个容易忽略的点：source install/setup.bash之后，如果之前已经source过别的 workspace，环境变量可能被覆盖。建议每次开新终端都重新source。
5.3 rosdep 解析失败
rosdep install --from-paths src --ignore-src -r -y报某个依赖找不到，先跑rosdep resolve <dep>看具体映射。如果映射为空，说明这个依赖不在rosdep的数据库里。解决办法是在rosdistro的rosdep目录下提 PR 添加映射，或者改用系统包名直接声明。
| 问题现象 | 可能原因 | 排查命令 | 解决方式 |
|---|---|---|---|
| colcon 找不到包 | package.xml 格式错误 | xmllint --noout package.xml | 修复 XML 格式 |
| ros2 run 找不到节点 | install 规则缺失 | 检查 CMakeLists.txt | 补 install(TARGETS) |
| rosdep 解析失败 | 依赖不在数据库 | rosdep resolve | 提 PR 或换依赖 |
| lint 测试失败 | 版权头缺失 | colcon test-result --verbose | 补版权声明 |
| bloom 报版本错误 | CHANGELOG 格式不对 | 对比规范模板 | 重写 CHANGELOG |
5.4 官方审核被拒的典型原因
我整理了几种最常见的被拒原因：LICENSE文件缺失或与package.xml里的声明不一致；README内容过于简单，没有说明包的实际用途；测试覆盖率太低，只有空测试；依赖声明不精确，用了depend但实际只在运行时需要；包名和已有包冲突。
审核者通常会在 PR 里留言指出具体问题，按照留言逐条修改就行。不要一次改完就重新提交，建议改完一条回复一条，这样审核者能快速确认。
5.5 版本号管理的经验
官方索引对版本号有“单调递增”的要求。如果你发布了0.1.0，下一次必须是0.1.1或0.2.0，不能回退。而且每次发布新版本，都要更新CHANGELOG.rst和package.xml里的版本号，两者必须一致。
我的做法是在package.xml里改版本号之后，立刻用catkin_generate_changelog生成对应的 changelog 条目，避免手动写错格式。这个工具虽然名字里有catkin，但在 ROS2 的bloom流程里同样适用。
6. 发布之后：维护与迭代的实际体会
包发布出去只是开始，后面的维护才是真正考验人的地方。我发布第一个包之后，陆续收到了几个 issue，有的是依赖版本冲突，有的是在特定平台上编译失败。这些反馈逼着我把 CI 配置补全，针对不同 Ubuntu 版本和 ROS2 发行版做矩阵测试。
CI 配置我用的 GitHub Actions，核心步骤就是装 ROS2、跑colcon build、跑colcon test。矩阵里覆盖humble和iron两个发行版，Ubuntu 覆盖jammy和noble。这样每次提 PR 都能提前发现兼容性问题，不用等官方审核的时候才暴露。
另外一个小技巧：在package.xml里把<maintainer>的邮箱设成一个你经常看的地址。官方审核和用户反馈都会发到这个邮箱，如果设成一个不常用的地址，很容易错过重要通知。我自己就因为用了旧邮箱，漏掉了一封审核询问邮件，导致 PR 多等了一周。
最后再分享一个关于CHANGELOG的实操细节：bloom在生成 deb 包的时候，会把CHANGELOG.rst的内容直接作为发行说明。如果 changelog 写得含糊，用户升级的时候根本不知道改了什么。所以每次发版，花十分钟把变更点写清楚，比事后补要省事得多。
