第一次在 ROS 2 里敲完ros2 pkg create盯着src下凭空冒出来的目录我确实愣了几秒包是建好了可它怎么变成能跑的节点答案就是colcon。它是 ROS 2 默认的构建工具负责把你的源码目录翻个底朝天、找出里面每一个包、算清包与包谁先谁后的依赖顺序再一个一个编译、安装最后给你一整套能让ros2 run认得出来的环境变量。说白了colcon就是 ROS 2 工作空间的总包工头——没有它你写的 C 节点和 Python 脚本都只是一堆躺在硬盘上的文本。这篇东西适合三类人看刚装完 ROS 2、还没搞明白build、install、log三个目录是干嘛的新手已经能跑起来、但每次改一行代码要等五六分钟的中间层以及手里管着几十个包、被依赖顺序和环境变量冲突折磨过的老手。我不打算把colcon --help抄一遍而是按它为什么这么设计 → 第一次怎么跑通 → 哪些参数真的能省时间 → 依赖和构建脚本怎么管 → 测试链路 → 踩过的坑怎么爬出来这条线走中间该给命令给命令该给参数就给计算过程。1. colcon 到底在构建什么从包发现到安装布局1.1 一次colcon build背后发生的四件事很多人以为colcon build等价于进每个包目录跑一次cmake make其实差得远。它本质上是一个包级调度器真正的编译工作交给每个包自己的构建系统去做。一次完整的构建会走四个阶段理解这四步后面所有的参数就都有了落脚点。第一步是包发现。colcon会从你当前目录开始递归往下扫识别出所有带package.xmlROS 包或者带COLCON_IGNORE之外可被识别标记的目录。这一步的关键在于它会自动跳过build、install、log这三个名字的目录也跳过任何含有COLCON_IGNORE空文件的目录——这一点非常重要否则你第二次构建时会把上次的安装产物当成源码再扫一遍直接把自己绕死。第二步是依赖图排序。拿到包列表后它读每个package.xml里的depend、build_depend、exec_depend、buildtool_depend构建一张有向图然后做拓扑排序。这就是为什么你改了一个底层接口包上层依赖它的包会自动重编也是为什么当出现循环依赖时colcon会直接甩给你一句Circular dependency然后罢工——它不会自作聪明地猜你想怎么办。第三步是逐包构建默认并行。每个包在自己的build/包名目录里独立跑 CMake或 setup.py编译产物不落地到源码目录这叫 out-of-source build。好处是你rm -rf build就等于一次干净的重新构建源码永远不受污染。第四步是安装与环境注册产物落到install/包名同时生成一堆setup.bash、local_setup.bash、package.dsv之类的环境脚本。你后面source install/setup.bash之所以能让ros2 run找到新包靠的就是这一步写进去的路径。提示colcon本身对什么是包是插件化识别的ament_cmake、ament_python、ament_cmake_python、纯cmake包它都认。所以同一个工作空间里混着 C 包、Python 包、甚至一个不依赖 ROS 的普通 CMake 库是完全正常的用法不是 hack。1.2 三个目录加一个日志为什么不能像以前那样只留一个devel如果你是从早期 ROS 1 的catkin_make转过来的最容易困惑的就是为什么多了个installdevel去哪了。这个变化不是没事找事而是为了解决一个非常具体的痛点安装空间和构建空间的职责分离。catkin_make时代的devel目录是半成品仓库——既有编译中间产物又有可以直接 source 的环境脚本。听着方便实际上带来两个问题。一是devel里的环境脚本是活的它指向的是构建目录里的库文件你一旦清掉某个包的构建产物环境变量还在运行时就会碰到明明 source 过了却找不到库的诡异现象。二是它很难做部分覆盖安装你想拿一个包的新版本盖掉系统里装好的旧版本路径优先级很容易乱。colcon的做法是把这两件事拆开build/只管编译中间态install/只管最终可用的产物log/存每次构建的完整输出。默认的isolated install模式下每个包在install/下有自己独立的子目录环境脚本通过package.dsv一条条把路径链起来。这样做的代价是路径长、环境变量条目多包多了以后AMENT_PREFIX_PATH能长到几百个字符但换来的是干净的可卸载性和明确的优先级——后 source 的覆盖先 source 的。对应的另一个选项是--merge-install把所有包的文件合并铺到install/根下路径短、环境变量少启动时扫描更快适合部署到资源紧张的板子上。但它的问题是文件互相覆盖时你很难追查是谁覆盖了谁。我的经验是开发机用默认的 isolated交付到嵌入式设备上再考虑--merge-install两边的取舍完全不同。log/目录经常被忽略其实是排查利器。log/latest_build/包名/stdout_stderr.log里存着那个包完整的编译输出command.log里存着实际执行的命令行。当你怀疑这参数到底传进去了没有直接看command.log比翻文档快得多。2. 第一次跑通从建目录到ros2 run成功2.1 建工作空间和第一个包标准动作没什么花样但顺序不能错。先建目录、再进src建包、最后回工作空间根目录构建——很多新手是在src里面直接敲colcon build然后发现install目录跑到src里去了越搞越乱。mkdir -p ~/ws_demo/src cd ~/ws_demo/src ros2 pkg create --build-type ament_cmake demo_node \ --dependencies rclcpp std_msgs cd ~/ws_demo colcon build--build-type这个参数要按包的实际类型选写 C 节点用ament_cmake纯 Python 脚本用ament_python。选错了不是不能编而是后面setup.py和CMakeLists.txt的模板对不上你得手工补一堆东西。--dependencies会顺手写进package.xml和CMakeLists.txt这是最省事的做法比事后手改两份文件可靠。构建成功的输出大概长这样Starting demo_node然后Finished demo_node [3.2s]最后一行Summary: 1 package finished [3.5s]。如果Summary里出现failed别急着往上滚屏先看最后那几行Failed 包名 [耗时]然后去log/latest_build/包名/stdout_stderr.log看真实错误。2.2 source 哪一条setup.bash和local_setup.bash的区别这是新手最容易含糊的一步而且含糊的后果很隐蔽——你可能 source 错了文件当时一切正常等到工作空间里包变多了才开始出诡异的版本不对问题。两个文件的差别在于是否递归。local_setup.bash只把当前这个工作空间install/下的路径加进环境变量不管它的依赖来自哪里。setup.bash则会顺着install/里记录的依赖前缀链把下层比如系统装的 ROS 2 主目录的环境也一起 source 进来。那到底该用哪个我的实际习惯是在新开的终端里第一次进入开发用source install/setup.bash一次到位。在已经 source 过底层环境的终端里切工作空间用source install/local_setup.bash避免重复叠加。为什么怕重复叠加因为source setup.bash是追加而不是替换。你在同一个终端里 source 三次AMENT_PREFIX_PATH里就有三份同样的路径LD_LIBRARY_PATH同理。绝大多数时候没事但当你想临时切到另一个工作空间编译出的另一个版本时优先级就会被旧路径挡住——你以为切过去了实际加载的还是老的.so。# 检查当前环境里到底叠了多少层 echo $AMENT_PREFIX_PATH | tr : \n看到重复项就该警惕了。最干脆的解法不是手工删而是新开一个终端。这也是我后来养成一个工作空间一个终端习惯的原因。2.3 验证闭环从编译到运行构建完、source 完验证三步走ros2 pkg list | grep demo_node看包认没认出来ros2 pkg executables demo_node看可执行文件注册上没有最后才是ros2 run demo_node xxx。很多人跳过前两步直接 run报错No executable found时就开始怀疑人生——其实九成是CMakeLists.txt里install(TARGETS ...)写了但没 source或者 source 的是local_setup.bash而底层环境压根没加载。对于 Python 包还有一个常被忽略的点setup.py里的entry_points决定可执行文件的名字console_scripts里写的是什么ros2 run就认什么。名字对不上包能 import 但跑不起来。3. 高频参数实测把十分钟的构建压到几十秒3.1 只编你改过的东西包选择系参数大工作空间里全量构建是最浪费时间的行为。colcon提供了一组按包筛选的参数用对了能省掉 90% 的等待。--packages-select是最直接的只编你点名的包不管依赖。适合我只改了 A 包的实现接口没动的场景。注意它不会帮你重编下游如果 A 的接口头文件签名、消息定义变了下游用的还是旧产物运行时会炸或者行为诡异。--packages-up-to是点名 它的全部依赖安全得多。改了一个底层库用它保证链条完整。--packages-above反过来选中依赖它的所有包适合接口改动后验证影响面。还有个--packages-above-and-dependencies两头都包做发布前回归时我一般直接用它。# 只编我改的那两个包以及依赖它们的下游 colcon build --packages-above src/my_iface src/my_driver # 只编指定包依赖用已有产物快但有风险 colcon build --packages-select my_driver # 跳过某个一直编不过的实验包 colcon build --packages-skip my_wip_pkg注意--packages-skip用久了容易忘。我见过有人在构建脚本里写死了 skip 参数三个月后接手的人死活找不出某个包为什么不更新。要跳就在命令行跳别写进脚本。3.2 并行度与内存--parallel-workers怎么定colcon默认按 CPU 核数并行。8 核机器同时跑 8 个包的编译听起来很美直到你编到一个模板满天飞的 C 包8 个g进程每个吃 1.5G 内存机器直接 OOMg被内核 kill 掉报错是一句莫名其妙的Killed (signal 9)。并行度的合理值不是核数而是可用内存 / 单包峰值内存。单包峰值怎么估看它在单线程下g的最大 RSS一个中等规模的消息处理包大概 800MB~1.5G重模板的能到 3G。你的机器 16G 内存、留 4G 给系统和 IDE剩 12G那并行度就是 12 / 1.5 ≈ 8看着还行但如果里面有 3G 的大包稳妥值是 4。# 保守并行适合内存吃紧的开发机 colcon build --parallel-workers 4 # 彻底串行排查并发相关的构建问题比如共享文件被同时写 colcon build --executor sequential--executor sequential和--parallel-workers 1效果接近但前者是把调度器都换掉了调试时更彻底。我在排查过两次并行构建时某个包的生成文件被另一个包读到半截的问题后养成了出怪错先串行跑一遍的习惯——如果串行能过八成是并行写冲突或者依赖声明漏了。3.3--symlink-install改 Python 脚本不用重编但有代价这个参数对 Python 包开发是降维打击。默认情况下你改了.py文件得重新colcon build才会同步到install/。加了--symlink-install之后install/里的文件变成指向源码的软链接改完存盘直接ros2 run就能看到效果省掉整轮构建。colcon build --symlink-install但它有三个代价得心里有数。第一软链只对非编译产物有效。C 的.so还是得真编这个参数救不了你。第二新增文件不会自动出现。你在CMakeLists.txt里加了一条install(FILES ...)必须重新 build 一次才会建出新的软链光改源码不够。第三删除源文件会留下断链某些工具碰到断链会报错install/目录看得也乱。还有一个隐蔽的坑--symlink-install的效果和你上次构建的模式是绑定的。你先用普通模式 build 过一次install 里是实体文件这次加--symlink-install再 buildcolcon会尝试覆盖但混着软链和实体文件的目录偶尔会出现改了没生效的错觉。我的做法是决定用--symlink-install就从一开始用中途切换前先rm -rf build install别省这一分钟。3.4 CMake 透传参数与常用组合表--cmake-args是把参数转给每个包的 CMake 配置阶段注意它后面要加--分隔否则colcon会把你后面跟的东西当成自己的参数。这是语法上最容易错的地方。# Release 构建默认是空 build type性能差很多 colcon build --cmake-args -DCMAKE_BUILD_TYPERelease # 只构建某个具体 target跳过测试和文档 colcon build --cmake-target install --packages-select my_pkg # 打开编译数据库给 clangd / IDE 用 colcon build --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDSON-DCMAKE_BUILD_TYPERelease这条我建议写进日常脚本。默认不指定 build type 时CMake 不会开任何优化你测出来的算法耗时比实际慢两三倍然后误以为是代码有问题。真实场景里我见过有人为了优化性能重写了整个数据处理流程最后发现是没开-O2。场景推荐参数组合说明日常改 Python--symlink-install --packages-select X秒级生效不重编 C改接口定义--packages-above src/iface带上受影响的下游首次全量--parallel-workers 4 --cmake-args -DCMAKE_BUILD_TYPERelease控制内存峰值发布前回归--packages-above-and-dependencies 串行宁可慢不可漏排查并发怪错--executor sequential --event-handlers console_direct输出实时顺序可靠部署到小设备--merge-install --install-base /opt/xxx路径短环境变量少顺带说--event-handlers console_direct默认的console_cohesion会把每个包的输出攒在一起全部结束才打印好处是日志整齐坏处是长时间构建时你完全不知道卡在哪。加上console_direct能看到实时滚动代价是多个包的输出会交错。串行调试时它几乎是必选项。4. 依赖声明与构建脚本让colcon少犯错4.1package.xml里的依赖写错了会怎样colcon的构建顺序完全依赖package.xml声明。少写一条构建顺序就可能错多写一条会引入不必要的重编。实践中最常见的错误是只写了运行依赖漏了构建依赖。比如某个包在CMakeLists.txt里find_package(std_msgs REQUIRED)但package.xml里只写了exec_dependstd_msgs/exec_depend。在本机可能因为环境里已经装好而侥幸编过换一台干净的机器就find_package失败而报错信息指向的是 CMake 找不到配置文件跟依赖漏声明这个真实原因隔了十万八千里。稳妥的写法是用depend这个聚合标签它同时覆盖 build 和 exec 两种。确实只需要运行期依赖的比如纯 Python 包只在运行中 import才用exec_depend。构建工具本身ament_cmake用buildtool_depend这类依赖不参与运行环境。还有一条依赖了某个包就一定要在package.xml里写哪怕 CMake 里没find_package。因为colcon排序和rosdep装依赖都只认package.xml。4.2colcon.meta给单包单独下参数当你有二十个包、但只有两个需要特殊 CMake 参数时命令行传参就不合适了——--cmake-args是全局生效的会给每个包都加一遍碰上不认识该参数的包直接编挂。colcon.meta就是解这个问题的。放在工作空间根目录用 JSON 描述哪个包用什么参数{ names: { heavy_pkg: { cmake-args: [-DCMAKE_BUILD_TYPERelease, -DENABLE_FAST_MATHON] }, debug_pkg: { cmake-args: [-DCMAKE_BUILD_TYPEDebug] } } }顶层的cmake-args键作用于所有包names下面的是单包覆盖。这个文件被colcon自动读取不需要额外参数指向它也可以用--metas显式指定路径。我在一个四十多个包的项目里用它把调试包必须带符号、性能包必须开优化这件事固定下来比每个人自己记参数靠谱得多。4.3 用COLCON_IGNORE隔离不该编的目录src下面放临时拷贝、旧版本备份、别人给的参考代码这些都不该被扫进去。最轻量的做法是在那个目录里丢一个空的COLCON_IGNORE文件touch src/reference_code/COLCON_IGNOREcolcon扫到它就整棵子树跳过不再往下找包。相比把目录挪走这个办法的好处是引用路径不用改代码还在原地只是不参与构建。这个文件还有个进阶用法把它放进build/和install/。虽然colcon默认会跳过这两个名字的目录但如果你用了--install-base或者--build-base指定到别的路径上名字就不叫build了递归扫描有可能把它们当源码扫进去然后你就会看到一大堆莫名其妙的package.xml解析错误。加个COLCON_IGNORE一劳永逸。5. 测试链路与日志构建之后还有半步没走完5.1colcon test和test-result是两件事很多人只跑colcon build从来不跑 test。等到 CI 上失败才发现自己本地有测试用例挂了半年。ROS 2 的测试生态还算完整ament_cmake包默认会注册gtest用例ament_python包可以挂pytest。colcon test --packages-select demo_node --event-handlers console_direct colcon test-result --verbose注意这是两条独立的命令而且第一条的返回码不一定是最终结果。colcon test负责跑但它对单个用例失败的处理相对宽容真正的结论要看colcon test-result它读build/包名/test_results/下的 XML 汇总。不加--verbose时它只报总数加上才会列出具体的失败用例和失败断言。还有一个细节colcon test默认不会重新构建。如果你改了代码没 build 就直接 test测的是旧产物。测试结果和代码状态对不上能让人怀疑人生半小时。我的习惯是固定写一行colcon build --packages-select X colcon test --packages-select X colcon test-result --verbose当成一个动作。5.2 日志目录的读法log/下面每次构建会生成一个带时间戳的目录latest_build和latest_test是指向最新一次的软链。结构是这样log/ ├── latest_build - build_2024-xx-xx_xx-xx-xx ├── latest_test - test_2024-xx-xx_xx-xx-xx └── build_2024-xx-xx_xx-xx-xx/ ├── events.log # 结构化的构建事件流 └── pkg_name/ ├── command.log # 实际执行的命令行 ├── stdout.log # 标准输出 ├── stderr.log # 标准错误 └── streams.log # 两者合并排查问题的正确顺序是先看stderr.log找错误关键词看不出来再看command.log确认参数是不是你以为的那样最后如果还是没头绪看events.log——它是 JSON 行格式的完整事件流能告诉你每个阶段的时间点和触发源。我遇到过一次很典型的案例加了--cmake-args -DCMAKE_BUILD_TYPERelease但性能一点没变。看command.log才发现参数确实传了但那个包自己的CMakeLists.txt里有一句set(CMAKE_BUILD_TYPE Debug)硬编码写死了把它覆盖回去了。这种问题看构建输出是看不出来的只有command.log加CMakeLists.txt对照才能定位。6. 踩坑实录六类典型故障和排查路径6.1 找不到包八成是环境没 source 对最高频的报错没有之一。Package xxx not found出现时先别怀疑代码按这个顺序查ros2 pkg prefix 包名看它认为包在哪。返回空或者报错说明AMENT_PREFIX_PATH里没有这个安装前缀。然后echo $AMENT_PREFIX_PATH看看你 source 的那个install目录到底在不在列表里。如果路径在但ros2 run还是找不到可执行文件那问题在包内部install/包名/lib/包名/下面有没有那个可执行文件没有的话是CMakeLists.txt的install(TARGETS ...)漏了有的话可能是可执行文件缺执行权限或者架构不匹配。还有一种很隐蔽的情况包里有两个同名可执行文件一个来自你本地编译一个来自系统安装ros2 run加载的是系统那个。用ros2 pkg executables 包名看不出区别得看which出来的实际路径。6.2 OOM 与Killed (signal 9)前面提过并行度的问题这里补充排查手法。构建中途某个包突然Failed日志里只有Killed基本可以确定是被内核的 OOM killer 干掉了。确认方法# 构建前后看一眼或者构建时另开终端盯着 dmesg -T | tail -20 | grep -i out of memory看到Out of memory: Killed process xxx (cc1plus)就是实锤。处理办法按代价从低到高降--parallel-workers把最重的那个包单独拎出来编--packages-select给机器加 swap治标构建会变慢但至少能过最后才是加内存。我个人更推荐拎出来单独编这个思路。因为真正吃内存的往往就一两个包把并行度整体降到 2 会让其他十几个小包的构建时间翻几倍不划算。6.3 切换--merge-install后环境错乱这是个容易自己给自己挖坑的操作。先用默认 isolated 模式构建环境一切正常某天为了部署试了一次--merge-install之后回到默认模式发现各种找不到库、符号未定义。原因是两种模式的install/布局完全不同isolated 是install/pkg/lib/merge 是install/lib/。切换时如果不清理旧的目录结构还在环境脚本却按新模式生成路径指来指去就错位了。铁律换安装布局前先rm -rf build install。没有例外。这一分钟省不得省了要花半小时排查。6.4 Python 改了不生效三个可能第一没用--symlink-install改完没重新 build。第二用了--symlink-install但改的是setup.py里的entry_points或者新增了文件这类改动必须重新 build 才会反映。第三最阴的一种——你的 Python 包在PYTHONPATH里有另一个副本import 时命中的是旧的。第三个怎么确认在节点里加一行打印import my_module print(my_module.__file__)打印出来的路径如果不是你工作空间里install/下那个就是路径污染。清理办法是新开终端只 source 当前工作空间。6.5 增量构建失效为什么每次都全量编正常情况下colcon是增量的build/包名里的 CMake cache 和 object 文件会被复用。如果你发现每次构建都像第一次一样慢检查两件事一是你是不是每次都手动rm -rf build有些人的构建脚本里写死了这行忘了删二是CMakeLists.txt里有没有configure_file之类的操作在每次配置阶段都改时间戳导致所有目标都被判定为过期。第二种比较隐蔽判断方法是连续跑两次 build看第二次耗时。正常应该是秒级如果还是几十秒就是有东西在每次配置时被弄脏了。看build/包名/CMakeFiles/下哪些.o被重编能反推出是哪个 target 受影响。6.6 依赖装的不是那个版本find_package(xxx REQUIRED)找到了但版本不对API 对不上编译报没有成员函数。这类问题在多工作空间叠加的环境里特别常见系统装了一份同事的工作空间装了一份你的AMENT_PREFIX_PATH里两个都在CMake 按顺序找到先出现的那份。排查用colcon info 包名看包的前缀路径或者直接在CMakeLists.txt里临时加一行message(STATUS xxx_DIR${xxx_DIR})把 CMake 实际用的配置文件路径打出来。看到路径不对劲就去调整 source 顺序或者干脆把冲突的那份从环境里摘掉。现象高概率原因第一步动作Package not found没 source / source 错文件echo $AMENT_PREFIX_PATHKilled (signal 9)并行导致 OOMdmesg查 OOM 记录降并行改了不生效未重编 / 路径污染打印模块__file__切换布局后报错残留旧 install 目录rm -rf build install每次全量重编构建脚本写死清理 / 时间戳脏连跑两次比对耗时符号未定义依赖版本冲突打印 CMake 实际配置文件路径我个人的习惯是把这些检查项直接写成一个小脚本放在工作空间根目录出问题先跑一遍能省掉大量从零开始回忆的时间。经验是colcon本身很少出错绝大多数问题出在环境变量叠加和依赖声明不全这两件事上把这两个根源盯紧了剩下的都是个案。